FWB DynObj Interfaces

Version 35, last updated by arst at Jul 14 15:06 2008 UTC

These interfaces are specific to File Workbench, but make use of the generic ones described here. They form a middle layer, between generic interfaces such as NotifierI, DynObj and specialized components such as maFileBrowser.

MiniApps and the !MiniAppManager

Many of the interfaces deal with MiniApps (similar to applets) and MiniAppManager, the host object, where the MiniApps are shown.

A MiniApp is essentially a small interactive rectangular area, where its content is shown. It can have small private toolbars, dedicated keyboard accelerators and some main window menus on its own. A number of MiniApps make up the full main window and the MiniAppManager coordinates them, adjusting their user interfaces and binding keys, depending on which MiniApp is active.

Two MiniApps can interact, they can look up each other, can query one another for interfaces and get notified when the other goes out of scope. Maybe the most obvious case is when FWB shows two File Browsers next to each other, and one can tab between them and they serve the role of source and target in file operations.

A third basic interface, MiniAppModeI, serves like a type object for a MiniApp. A MiniApp has one such object as its own type. Then, additional MiniAppModes can be added to a MiniApp at run time. Such MiniAppMode represents added functionality (plugins and extensions).

FWB has a built-in editing mode for dialog layouts, available from the FWB text editor. This MiniAppMode is activated once it recognizes some dialog markup inside the file. Then its toolbar is shown and one can ‘compile’ and visualize the dialog as one edits its markup. When a file with no dialog markup in it is opened, this mode quietly hides itself.

Other examples of MiniAppModeI extensions include:

Extensions to a text editor for various editing modes (C++, Squirrel, …).
Extensions to command prompts that does file name completion.
Extensions to File Browsers that add lines to a popup menu.

MiniAppModes are associated with a MiniApp through a negotiation process. For example, an XmlMiniAppMode might only associate itself with a text editor if its current file name ends with .xml. So, the addon modes are context sensitive and can be activated and made visible only when they are needed.

h2. Interfaces

h4. WindowI

This is the base interface for MiniApp. It contains the more general functionality of MiniAppI (activation, create/destroy functions and holding a label / caption).

Note: It does not represent a fully functional OS level window (although it probably uses one under the hood).

Base class	DynObj
File	dynobj/WindowI.h
Methods	void GetWinHndl()*	Returns the native window handle if any.
	bool GetLabel( DynStr& ds )	Return the label/caption of the window.
	bool SetLabel( const char label )*	Sets the label/caption of the window.
	void OnActivate( bool activating )	Called when the window is activated / deactivated.
	void OnCreated( )	Called when the object has been created.
	void OnDestroy( )	Called just before the object is destroyed.

CmdHandlerI

This interface represents an object that receives commands, and can answer if it can handle a command or not. A MiniApp may implement the CmdHandlerI and another object can query for this interface using: do_cast<CmdHandlerI*>( MiniAppI* pma ).

Base class	None
File	dynobj/DoWindowI.h
Methods	int GetCmdState( int cmd_id )	Query if the object can handle this command and if it’s enabled.
	int OnCommand( int cmd_id, const char cmd_str )*	Called when invoking a command on the object.

h4. MiniAppI

This is the interface representing a visible MiniApp. A MiniAppI typically has a type (MiniAppType) and is affected by commands (dispatched by its MiniAppModes).

Base class	WindowI
File	mam/MiniAppManagerI.h
Methods	void OnAddMode( MiniAppModeI pmode, bool is_adding )*	Called when a mode has accepted this app. Also called when the mode is removed.
	int OnChangeManager( MiniAppMgrI pmgr_new )*	Called when a MiniApp is moved to a new manager (another main window)

h4. MiniAppManagerI

This interface represents the main window, the host of the MiniApps. Only one MiniApp is active at any one time and them MiniAppManager holds their shared resources and makes sure that menus, toolbars and the keyboard are updated when the active MiniApp changes.

Base class	DynObj
File	mam/MiniAppManagerI.h
Methods	void MiniAppI pma, const maChar* caption)*	Sets the caption for this MiniApp.
	bool AllocStatusBarField( MiniAppTypeI pmati, int pixel_size, bool right_side )*	Allocates space on the statusbar for the given MiniAppType.
	bool AssociateModes( MiniAppI pma )*	Iterate all available MiniAppModes and redo the association process (with the pma MiniApp).
	bool AddMode( MiniAppModeI pmode, MiniAppI* pma )*	Make the given mode available to MiniApps. If pma is NULL, it is tested against all existing ones, otherwise only with pma.
	bool RemoveMode( MiniAppModeI pmode, MiniAppI* pma )*	Make the given mode unavailable to one or all MiniApps. If pma is NULL, it is made unavailable for all.
	bool SetCmdState( MiniAppI pma, int id_cmd, int state_mask, int state )*	Changes the state of a command (enabled/disabled, checked, …)
	bool Activate( MiniAppI pma, bool do_focus )*	Makes a MiniApp visible and gives it keyboard focus if do_focus is set.
	MiniAppI GetMiniAppByName( const maChar* name )*	Find a MiniApp with given name.
	MiniAppI GetMiniAppByType( const maChar* type, int index)*	Find a MiniApp with given type. Can iterate with index.
	MiniAppI GetClosestMiniAppByType( MiniAppI* pself, const maChar* type, bool also_same_pane )*	Find the MiniApp with given type that is closest to pself.
	MiniAppI CreateMiniApp( const maChar* type, const maChar* name, MiniAppI* at_pma, Location loc )*	Creates a new MiniApp with given type and name, at the location described by loc (Left/Right/Floating/…).
	bool ChangeMiniAppSetting( MiniAppI pma, Setting s, Change action )*	Changes the given setting for a MiniApp (show/hide toolbar, caption, …).
	bool EditActiveCaption( )	Starts editing the caption of the active MiniApp.
	MiniAppTypeI GetMiniAppType( const maChar* type )*	Retrieve MiniAppTypeI for the given app.
	MiniAppTypeI GetMiniAppTypeFromApp( MiniAppI* pma )*	Retrieve the MiniAppTypeI of pma.
	NAT_WIN_HNDL GetWinHndl( )	Gets the native window handle of the MiniAppManager.

h4. MiniAppModeI

This is the interface that gives a MiniApp its type and its add-on capabilities.

Handling of command IDs (plain integers) is perhaps the most important job of a MiniAppMode. Each ID has additional information stored with it, such as help strings, flags and small bitmaps for buttons/menus. When the function GetCommandEntry(int ix) is called, a mode responds with a list of command IDs it can handle. Using this information, the MiniAppManager can prepare the user interface and will know which IDs the mode can handle. Different types of MiniApps may reuse the same ID ranges, the manager sends the ID to the active one.

Some IDs refer to tool bars or menus. Typically a menu or tool bar can contain multiple items, so a MiniAppMode can deal with lists of command IDs.

Base class	DynObj
File	mam/MiniAppManagerI.h
Methods	const maChar GetTypeName( )*	Returns a human readable descriptive name of this mode/type.
	const maChar GetDescription( )*	Returns a description of this mode/type.
	const maChar GetBaseType( )*	Returns the base type/mode (if any). A type automatically re-uses commands from its base type.
	const void GetIcon(bool& is_xpm_mem )*	Returns the icon to use for this type/mode. Returns either a file name or a pointer to XPM data.
	int AcceptApp( MiniAppTypeI ptype, MiniAppI* pma )*	Returns >0 if the type (and the app pma) can be accepted by this mode. If pma is NULL, the call is a question if the ptype is potentially acceptable or not.
	NAT_WIN_HNDL CreateToolControl( MiniAppI pma, int id_tool, NAT_WIN_HNDL toolbar_hndl )*	Creates a toolbar control based on id_tool. It will be put inside toolbar_hndl, the native window handle for the toolbar we’re building.
	maCommand GetCommandEntry( int ix )*	This returns a command descriptor structure for ID number ix (or NULL if at the end).
	maIdListInfo GetIdListInfo(int ix_list)	This returns a structure describing a list of IDs (such as a menu or a toolbar).
	int GetIdToolbar( int ix )	Returns the ID of toolbar number ix (or MA_ID_NONE if no more toolbars).
	int GetIdStaticMenu( )	Returns the ID of static menu (always shown) for this type.
	int GetIdDynamicMenu( )	Returns the ID of dynamic menu (shown when a MiniApp of this type has focus).
	maAccelerator GetAccelerator( int ix )*	Returns a structure describing a keyboard accelerator for this type.
	const maChar GetRelatives( )*	Returns a string describing relationships (roles and types) that this mode may have with others (used for automatic setup)
	bool OnCommandId( MiniAppTypeI ptype, int cmd_id )*	Called when a executing the command cmd_id. Returns true if the command was handled.
	void OnStatusBarClick( MiniAppI ma, int field_ix, int mouse )*	Called when a status bar field (allocated by this type) is clicked.
	void OnActivate( MiniAppI pma, bool activating )*	Called when a MiniApp of this type is activated (or looses focus).

h4. MiniAppTypeI

This is the interface to the primary type of a MiniApp. A MiniApp have precisely one MiniAppType but may have several MiniAppModes. The type object does very much the same as the mode objects, so it inherits from MiniAppModeI.

MiniAppTypes include:

maFileBrowser – A MiniApp for browsing files in a directory.
maTextEditor – A text editing MiniApp.
maCommandPrompt – A command prompt MiniApp.

These types can then be extended with any number of modes.

Base class	MiniAppModeI
File	mam/MiniAppManagerI.h
Methods	bool Init( MiniAppMgrI pmgr )*	Initializes the type and associates it with a manager.
	void UnInit( )	Called when the type is not used any more by any manager.
	MiniAppI Create( const maCreateParam& cparam )*	Create a new MiniApp of this type, using parameters of cparam.
	const maChar GetDefaultName( )*	Returns a name to be used as default by new apps of this type.
	int GetFlags( )	Returns flags specifying capabilities / limitations of apps of this type.

File Workbench