Редактирование: Embedding HIViews in Qt/Mac Applications

[[Категория:Qt_Издания]]
__NOTOC__

by Trenton Schulz
<div class="introduction">
Unlike earlier Qt versions, Qt 4 for Mac OS X is built on the top ofthe HIToolbox APIs which form Apple's modern Carbon interface. Thismeans that Qt can interact with other HIToolBox APIs for extrafunctionality. We'll take a look at this by showing how to embedHIViews inside a Qt application.

*[[#gettingstarted | Getting Started]]
*[[#usinghimovieview | Using HIMovieView]]
*[[#usinghiwebview | Using HIWebView]]
*[[#conclusion | Conclusion]]
</div>
When Qt was originally introduced on Mac OS X, a Qt window consisted of awindow with regions for various areas of the widgets. While this allowed us todo quite a bit with our widgets, it made it very difficult to integrate Qtwidgets with other applications or vice versa. Typically, one worked around thisby using separate windows or by possessing intimate knowledge of how Qt dealtwith widgets, but this was hardly optimal.

We wanted to remove this limitation in Qt 4, so we jumped onto the HIViewbandwagon. This was Apple's new way of creating their own widgets in the Carbonworld. This meant that every [[Qt:Документация_4.3.2/qwidget  | QWidget]] was now a HIView and could be manipulatedand used just like other HIViews. This also gave us the benefit of compositingwithout any extra work on our part.

Still, it was not all perfect. You could now embed Qt widgets in other non-Qtwindows and vice versa, but it wasn't straightforward. It still requiredknowledge about how Qt deals with events and some custom code to set it up.It was certainly possible, but more work than you would typicallyexpect when using Qt.

For Qt 4.2, dropping support for Mac OS X 10.2 suddenly allowed us toput [[Qt:Документация_4.3.2/qwidget  | QWidget]]s inside menus. Since we were working on putting Qtwidgets in non-Qt windows, we decided to go a bit further and make iteasy for anyone to add a HIView into a [[Qt:Документация_4.3.2/qwidget  | QWidget]].

With Qt 4.2, it is easier than ever to embedother Carbon HIViews (hereafter referred to as just "views") in Qt.

[[Image:qq20-hiviews-qthimovie.png|center]]
<div id="gettingstarted"></div>
===Getting Started===

In general, adding a standard view to a Qt widget hierarchy basically involvesthe following steps:

*Wrap the view into a [[Qt:Документация_4.3.2/qwidget  | QWidget]] subclass.
*In the constructor, create your view and pass the <tt>HIViewRef</tt> to theprotected [http://www.crossplatform.ru/documentation/qtdoc4.3/qwidget.php#create QWidget::create()] function.
*Wrap any additional functions that map into Qt concepts.
*Wrap any other view-specific functionality depending on how much you wantit to interact with other widgets.

Steps 3 and 4 are optional. With a little effort, you can make a custom viewact very much like a Qt widget, complete with properties, signals and slots.If all you need to do is "just get the thing in there", you can stop atstep 2.
<div id="usinghimovieview"></div>
===Using HIMovieView===

It makes most sense to embed something that is a bit different to a standardQt widget. So, let's take a <tt>HIMovieView</tt> and add it to a Qt window.

<tt>HIMovieView</tt> is a new view in Mac OS X 10.4 (Tiger) or QuickTime 7 and it letsyou play QuickTime content. In previous versions of Mac OS X, there was the older"Movie Control", but <tt>HIMovieView</tt> adds simplicity and performance at the priceof only being available on systems with QuickTime 7. Unfortunately, it willonly be a 32-bit option on future versions of Mac OS X.

Regardless, it's still a great view for illustrating how to embed views in Qtwithout complicating the example unnecessarily. Here's the class declaration:
<source lang="cpp-qt">
class MovieWidget : public QWidget
{
    Q_OBJECT
    Q_PROPERTY(bool nativeControlsVisible
               READ nativeControlsVisible
               WRITE setNativeControlsVisible)

public:
    MovieWidget(QWidget *parent = 0);
    ~MovieWidget();

    bool nativeControlsVisible() const;
    void setNativeControlsVisible(bool visible);

    QSize sizeHint() const;

signals:
    void optimalSizeChanged();

public slots:
    void loadMovie(const QString &amp;fileName);

private:
    Movie currentMovie;
};
</source> 
Our movie widget isn't too different than most widgets. We have a propertyindicating whether or not we want to have the native QuickTime controls. Weimplement <tt>sizeHint()</tt> because movies generally have a certain size they want tobe shown in. We also provide a signal so that a window can catch any suchchange, and we've provided a <tt>loadMovie()</tt> slot.
<source lang="cpp-qt">
MovieWidget::MovieWidget(QWidget *parent)
    : QWidget(parent),
      currentMovie(0)
{
    HIViewRef movieView;

    HIObjectCreate(kHIMovieViewClassID, 0,
            reinterpret_cast<HIObjectRef *>(&amp;movieView));

    HIMovieViewChangeAttributes(movieView,
            kHIMovieViewAutoIdlingAttribute
            | kHIMovieViewControllerVisibleAttribute, 0);
    
    create(WId(movieView));

    setSizePolicy(QSizePolicy::MinimumExpanding,
                  QSizePolicy::MinimumExpanding);
}  
</source> 
Our constructor creates an instance of <tt>HIMovieView</tt> and sets itsattributes. You may wonder why we do this with the rather generic<tt>HIObjectCreate()</tt> and not the documented <tt>HIMovieViewCreate()</tt>function. This is to work around a bug in QuickTime 7.0. For laterversions of QuickTime, we could use <tt>HIMovieViewCreate()</tt>.

After we have done that, we call the [http://www.crossplatform.ru/documentation/qtdoc4.3/qwidget.php#create QWidget::create()]function, which will set the <tt>HIViewRef</tt> as this [[Qt:Документация_4.3.2/qwidget  | QWidget]]'s window ID.From here, we can always get back the <tt>HIViewRef</tt> by calling <tt>winId()</tt> andcasting it.

Since movies have a minimum size and look fine when expanded, weadjust our size policy accordingly.
<source lang="cpp-qt">
MovieWidget::~MovieWidget()
{
  if (currentMovie != 0)
        DisposeMovie(currentMovie);
}
</source> 
Our destructor cleans up the current movie &emdash; leaking movies can be expensive.
<source lang="cpp-qt">
bool MovieWidget::nativeControlsVisible() const
{
    OptionBits currentBits = HIMovieViewGetAttributes(
        HIViewRef(winId()));
    return kHIMovieViewControllerVisibleAttribute &amp;
           currentBits;
}

void MovieWidget::setNativeControlsVisible(bool visible)
{
    if (visible != nativeControlsVisible()) {
        HIMovieViewChangeAttributes(HIViewRef(winId()),
          visible ?
            kHIMovieViewControllerVisibleAttribute : 0,
          !visible ?
            kHIMovieViewControllerVisibleAttribute : 0);
        updateGeometry();
        emit optimalSizeChanged();
    }
}
</source> 
Our native controls property simply passes values through to the<tt>HIMovieView</tt> API, insulating us from the more clumsy "change attributes"pattern.

Because changing the visibility of the control changes its size, we need toupdate our geometry and emit a signal to indicate that it has changed, soothers can take this into account.

The <tt>loadMovie()</tt> slot may look complex, but it is primarily set up forQuickTime. Since QuickTime has its own documentation, we'll gloss over most ofthe details.
<source lang="cpp-qt">
void MovieWidget::loadMovie(const QString &amp;fileName)
{
    QTVisualContextRef visualContext = 0;
    Boolean active = true;
    DataReferenceRecord dataRef;
    Movie oldMovie = 0;

    QTNewMoviePropertyElement newMovieProperties[] = {
        { kQTPropertyClass_DataLocation,
          kQTDataLocationPropertyID_DataReference,
          sizeof(dataRef), &amp;dataRef, 0 },
        { kQTPropertyClass_NewMovieProperty,
          kQTNewMoviePropertyID_Active,
          sizeof(active), &amp;active, 0 },
        { kQTPropertyClass_Context,
          kQTContextPropertyID_VisualContext,
          sizeof(visualContext), &amp;visualContext, 0 }
    };

    CFStringRef cfString = CFStringCreateWithCharacters(0,
            reinterpret_cast<const UniChar *>(
                fileName.unicode()), fileName.length());
    QTNewDataReferenceFromFullPathCFString(cfString,
            kQTPOSIXPathStyle, 0, &amp;dataRef.dataRef,
            &amp;dataRef.dataRefType);
    CFRelease(cfString);
</source> 
The key point is that we first need to create a QuickTimereference to the file. We do this by converting our [[Qt:Документация_4.3.2/qstring  | QString]] to a CoreFoundation string (<tt>CFStringRef</tt>). Since each <tt>CFStringRef</tt> isreference-counted, we need to remove our reference to it when we are done withit by calling <tt>CFRelease()</tt>.

We replace the old <tt>Movie</tt> with a newly-created one and perform all thenecessary housekeeping to keep QuickTime happy, then we use the<tt>HIMovieViewSetMovie()</tt> function to embed the <tt>Movie</tt> into ourwidget:
<source lang="cpp-qt">
    oldMovie = currentMovie;
    currentMovie = 0;

    NewMovieFromProperties(sizeof(newMovieProperties) /
        sizeof(newMovieProperties[0]),
        newMovieProperties, 0, 0, &amp;currentMovie);
    DisposeHandle(dataRef.dataRef);
    HIMovieViewSetMovie(HIViewRef(winId()), currentMovie);
    if (oldMovie != 0)
        DisposeMovie(oldMovie);

    updateGeometry();
    emit optimalSizeChanged();
}
</source> 
Before we return, we call <tt>updateGeometry()</tt>, emitting our custom<tt>optimalSizeChanged()</tt> signal to indicate that the size has changed.
<source lang="cpp-qt">
QSize MovieWidget::sizeHint() const
{
    EventRef event;
    HIRect optimalBounds;
    CreateEvent(0, kEventClassControl,
        kEventControlGetOptimalBounds,
        GetCurrentEventTime(),
        kEventAttributeUserEvent, &amp;event);

    SendEventToEventTargetWithOptions(event,
        HIObjectGetEventTarget(HIObjectRef(winId())),
        kEventTargetDontPropagate);

    GetEventParameter(event,
        kEventParamControlOptimalBounds, typeHIRect,
        0, sizeof(HIRect), 0, &amp;optimalBounds);

    ReleaseEvent(event);
    return QSize(optimalBounds.size.width,
                 optimalBounds.size.height);
}
</source> 
The <tt>HIMovieView</tt> implements a Carbon event called<tt>kEventControlGetOptimalBounds</tt> that we can use for calculating the<tt>sizeHint()</tt>.Since Carbon does not have such things as virtual functions, we follow theCarbon pattern of sending the event and getting the information back which isreturned in an <tt>HIRect</tt>. We can then return the new optimal size.Now that we've created our <tt>HIMovieView</tt>, we can put it into a widgethierarchy, make [[Qt:Документация_4.3.2/qobject  | QObject]] connections and do otherthings that you would expect with any other widget. As illustrated here:
<source lang="cpp-qt">
Window::Window(QWidget *parent)
    : QWidget(parent)
{   
    setupUi(this);

    movieWidget = new MovieWidget(this);
    connect(this, SIGNAL(movieChosen(QString)),
            movieWidget, SLOT(loadMovie(QString)));
    connect(movieWidget, SIGNAL(optimalSizeChanged()),
            this, SLOT(updateSizes()));
    layout()->addWidget(movieWidget);
    ...
}
</source> 
Since we are using QuickTime, we need to initialize the QuickTime environment.The typical place to do this is in the <tt>main()</tt> function:
<source lang="cpp-qt">
int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    EnterMovies();              // initialize QuickTime
    Window movieWindow;
    movieWindow.show();
    QMetaObject::invokeMethod(&amp;movieWindow, "chooseMovie",
                              Qt::QueuedConnection);
    int ret = app.exec();
    ExitMovies();               // uninitialize QuickTime
    return ret;
}
</source> 
The call to <tt>EnterMovies()</tt> initializes the QuickTime environment, while<tt>ExitMovies()</tt> does the necessary tear down.

Now we can watch movies like, for example, the "Qt 4 Dance" inside Qt.
<div id="usinghiwebview"></div>
===Using HIWebView===

Another popular view that developers may want to use is <tt>HIWebView</tt>. Ofcourse, <tt>HIWebView</tt> could be considered "androgynous" since it is actuallya Cocoa <tt>WebView</tt> that is then wrapped inside a Carbon API. This isthe only Cocoa view that is available in Carbon and it entails a number ofissues. One of them is that it can't really be composited with other widgetsin the widget hierarchy (i.e., you can't put other views on top of it).

Also, the Cocoa view haswhat would be referred to in X11 as "southwest gravity" which means that itexpands "up and to the right". This is all well and good, but the Carbon viewthat wraps it has "northwest gravity" which means that you will have somestrange resizing behavior if you don't handle the laying out of the views.Using [[Qt:Документация_4.3.2/qlayout  | QLayout]] helps shield you from this problem.

Another thing to beaware of is that <tt>HIWebView</tt> functions just create the view, the majority ofthe heavy lifting must be done through the Cocoa class. So, depending on howadvanced you want to be, you may need to take a look at Objective-C/Cocoa.

Despite these issues, creating and embedding an <tt>HIWebView</tt> is not that muchdifferent than the <tt>HIMovieView</tt> above. We'll take a look at creating thewidget and setting a URL on it:
<source lang="cpp-qt">
WebWidget::WebWidget(QWidget *parent)
    : QWidget(parent)
{
    HIViewRef webView;
    WebInitForCarbon();
    HIWebViewCreate(&amp;webView);
    create(WId(webView));
}
</source> 
This is similar to what we had to do with <tt>HIMovieView</tt>. We first call our<tt>WebInitForCarbon()</tt>, a WebKit function that initializes the various bitsfor using WebKit. We then call <tt>HIWebViewCreate()</tt> to create our<tt>HIWebView</tt>, we then pass it along to the [http://www.crossplatform.ru/documentation/qtdoc4.3/qwidget.php#create QWidget::create()] function.At that point we have successfully created an <tt>HIWebView</tt>.

The <tt>setUrl()</tt> function mixes the fun of C, C++, and Objective-C into onefunction! Setting a URL on the <tt>HIWebView</tt> requires us to convert our[[Qt:Документация_4.3.2/qurl  | QUrl]] to a <tt>NSURL</tt> and tell the web view to load it.
<source lang="cpp-qt">
void WebWidget::setUrl(const QUrl &amp;url)
{   
  if (!url.isValid())
      return;

    QString qurlString = url.toString();
    CFStringRef urlStr = CFStringCreateWithCharacters(0,
        reinterpret_cast<const UniChar *>(
            qurlStr.unicode()), qurlStr.size());
    CFURLRef urlRef = CFURLCreateWithString(0, urlStr, 0);

    WebView *cocoaView = HIWebViewGetWebView(
                         HIViewRef(winId()));
    NSURLRequest *request = [
        NSURLRequest requestWithURL:(NSURL *)urlRef];
    [[cocoaView mainFrame] loadRequest:request];

    CFRelease(urlStr);
    CFRelease(urlRef);
}
</source> 
We accomplish our conversion by making a <tt>CFStringRef</tt> from the[[Qt:Документация_4.3.2/qstring  | QString]] representationof the [[Qt:Документация_4.3.2/qurl  | QUrl]]. We create a <tt>CFURLRef</tt> from this <tt>CFStringRef</tt>.We then use Apple's "toll-free bridging" concept (which boils down to thefact that the <tt>CFURLRef</tt> is interchangeable with a <tt>NSURL</tt> pointer) tocreate a <tt>NSURLRequest</tt> which we can then feed to the web view's renderingframe. We remove our references at the end of the function to keep thingsfrom leaking.Since we are mixing both Objective-C and C++ in the same source file, we savethe file with a <tt>.mm</tt> extension to indicate that it is an Objective-C++ file. Wealso put it in the <tt>OBJECTIVE_SOURCES</tt> area of our <tt>.pro</tt> file (instead ofthe regular <tt>SOURCES</tt> section), as shown below.
<source lang="cpp-qt">
HEADERS += webwidget.h window.h
FORMS += window.ui
SOURCES += main.cpp window.cpp
OBJECTIVE_SOURCES += webwidget.mm

LIBS += -framework WebKit
</source> 
Finally, here's a screenshot of the above <tt>WebWidget</tt>.

[[Image:qq20-hiviews-qthiwebview.png|center]]

As mentioned above, this is really just scratching the surface for<tt>HIWebView</tt>; if you want full functionality (like knowing when a web pagehas been downloaded, updating the address bar when a link is clicked, etc.),you need to work with delegates, listeners, and other Cocoa/Objective-Cpatterns. We'll leave that to other documentation projects.

<div id="conclusion"></div>
===Conclusion===


With Qt 4.2, the process of embedding HIViews is fairlystraightforward. We've seen that the basics of creating them are moreor less the same for two of the more complex views out there.Hopefully, being able to embed HIViews will make development with Qt/Maca bit more of a cosmopolitan experience.

The full source code for the examples in this article can be downloadedfrom the ''Qt Quarterly'' website.


<hr />
{| width="100%"

|-
|Copyright &copy; 2007 Trolltech
| align="right" | [http://www.trolltech.com/trademarks.html Trademarks]
|}