iMedia2 DocumentationThis page will host the documentation for maintainers of the iMediaBrowser.framework (version 2.x), as well as documentation for application developers using the framework in their apps. Chapters 1 and 2 are recommended reading if you want to understand the internal architecture of the framework, contribute to its future development, or write new parser classes. These chapters are also helpful if you want to customize iMediaBrowser (chapter 4). If you are an application developer that simply wants to use the standard behavior of the framework in your own app, then you can skip ahead to chapter 3. The standard user interface of iMediaBrowser looks like this: 
1. Architecture1.1 The Model ClassesThe model is divided into three groups: media types, nodes, and objects. The screenshot above shows where In the standard user interface each kind of model class is displayed. 1.1.1 Media TypesiMedia currently defines 4 different media types, but new ones can be added easily if the need arises. The constants for media types are defined in IMBCommon.h: extern NSString* kIMBMediaTypeImage;
extern NSString* kIMBMediaTypeAudio;
extern NSString* kIMBMediaTypeMovie;
extern NSString* kIMBMediaTypeLink; 1.1.2 IMBNodeNodes are displayed in the upper part of the standard iMediaBrowser panel. They are either displayed in an NSOutlineView or in an NSPopUpButton. The model class for a node is IMBNode. For each row in the NSOutlineView, there is an instance of IMBNode. IMBNode is a fairly big class with lots of properties. Although almost all of these properties have setters and getters you should essentially regard instance of IMBNode as "immutable", i.e. once a node has been created and all properties are set, this nod eis not to be modified anymore. If for any reason a node needs to be updated with new values, a new instance is created and the original instance is replaced with the new instance. This mechanism is described in more detail in IMBLibraryController and the chapter 2 (Writing a Parser Class). The most important properties of IMBNode are: @property (copy) NSString* identifier;
@property (copy) NSString* name;
@property (retain) NSImage* icon;
@property (retain) NSArray* subNodes;
@property (retain) NSArray* objects; The identifier is a string that uniquely identifies a node in the tree. This string must be unique across media types, parsers, and across application launches, as the identifier is used for a multitude of jobs. It controls persistance of selection and expanded state, and is also responsible for replacing old with new instances. Name and icon should be evident. These are directly visible in the user interface. The subnodes array is used to construct a node tree. The objects array is used to represent item of a given media type, e.g. images, songs, or movies. If the subNodes or object array is nil, a node is considered to be "unpopulated" - i.e. it is in an incomplete state. Once an unpopulated node is selected or expanded in the user interface, the controllers will trigger appropriate actions to populate this node (with subnodes and objects). 1.1.3 IMBObjectTO DO 1.1.4 IMBObjectPromiseSince objects can represent media files on the local file system, remote servers on the internet, camera devices, or possibly other locations, we need an abstraction mechanism that provides a common API to access all the media files, regardless of their location. IMBObjectPromise provides this API. IMBObjectPromise is used for double clicking, dragging, or opening media files via context menu items. An instance of IMBObjectPromise is initialized with an array of IMBObjects (usually the selected objects, or in the case of a context menu the clicked object). Loading of the media files is triggered with the method -startLoadingWithDelegate:finishSelector:. Once loading has concluded the finishSelector is called on the delegate. This mechanism is can be used for double clicking - in this case the framework does everything for you. IMBObjectPromise can also be used fro drag & drop operations. The IMBObjectPromise instance is created with an array of objects and then put onto the pasteboard. When you receive a drop in your own client application, you can retrieve the IMBObjectPromise instance from the pasteboard, start loading, and once the finishSelector is called, you can retrieve the downloaded files. You also have the option of implementing your own custom loading progress. 1.2 The Controller ClassesTO DO 1.2.1 IMBParser1.2.2 IMBParserController1.2.3 IMBLibraryController1.2.4 IMBNodeViewController1.2.5 IMBObjectViewController1.2.6 IMBObjectArrayController1.3 The View ClassesTO DO 2. Writing a Parser ClassTO DO 3. Using the Framework in Your AppiMediaBrowser can be used with default behavior that requires very little work on your part, or it can be customized (but that requires a lot more work). The default user interface is shown at the top of this page. Using the default standalone panel in you app is pretty easy. # Link your application against iMedia.framework # #import <iMedia/iMedia.h> # When you need the standalone panel, call the following three lines: NSArray* mediaTypes = [NSArray arrayWithObjects:kIMBMediaTypeImage,kIMBMediaTypeAudio,kIMBMediaTypeMovie,kIMBMediaTypeLink,nil];
IMBPanelController* panelController = [IMBPanelController sharedPanelControllerWithDelegate:self mediaTypes:mediaTypes];
[panelController showWindow:nil]; You can also call sharedPanelController to return the existing panel controller, creating a default panel controller with no delegate and default media types if it's not created yet, or sharedPanelControllerWithoutLoading to return any existing panel controller, or nil if it's not loaded yet — useful if you are trying to close down the media browser if it's open. The contents of this panel and the behavior can be customized by implementing various delegate methods. Please refer to the source code in IMBTestAppDelegate.m for examples and have a look at the headers files of the various controller classes for info on all delegate methods. There are various different controller protocols. The methods all get passed (sometimes with detours) to your delegate: - IMBParserControllerDelegate
- IMBLibraryControllerDelegate
- IMBObjectArrayControllerDelegate
- IMBObjectViewControllerDelegate
- IMBPanelDelegate
If the degree of customization which is possible by implementing these delegate methods does not suffice for your needs, please refer to chapter 5 to find out how you can build custom user interfaces and behaviors by manually combining the components of the framework, possibly also subclassing some classes.
3.1 Migrating from iMedia 1(If you were using the older version of iMedia Browser, be sure to really clean out your build before trying to bring in the new imedia, so you don't have conflicts!) iMediaBrowser -> IMBPanelController iMediaBrowser sharedBrowserWithDelegate -> IMBPanelController sharedPanelControllerWithDelegate:mediaTypes: 4. Notes on Customizing and SubclassingTO DO
History- 10/31/09 PB: Created this page
- 11/01/09 PB: Added some content to chapter 4
|
Sign in to add a comment
