IFrameHandler

The IFrameHandler class handles frame window events. Usually, when you construct an IFrameWindow object, the function IFrameWindow::start attaches an IFrameHandler object to the frame window.

When you use any of the protected member functions, IFrameWindow::create, IFrameWindow::tryToLoadDialog, or IFrameWindow::initialize, and you do not specify the style IFrameWindow::deferCreation, the frame constructor calls IFrameWindow::start.

If you construct the frame window using some alternate means (for example, by a derived class of IFrameWindow) and IFrameWindow::start is not called, either call IFrameWindow::addDefaultHandler to cause the frame to attach an IFrameHandler object to itself or create a handler derived from IFrameHandler and attach it to the IFrameWindow object. You can attach the handler derived from IFrameHandler by calling IHandler::handleEventsFor to pass the appropriate frame window to the handler.

To attach a handler derived from IFrameHandler to a frame window that already has an IFrameHandler object attached to it, you must first call IFrameWindow::removeDefaultHandler. Otherwise, events can be processed twice, causing unpredictable results. If your handler overrides the dispatchHandlerEvent function, be sure that you arrange for the IFrameHandler::dispatchHandlerEvents function to be called once for all events that you do not process in your handler. This is because the processing of events is needed to cause the correct frame window behavior.

IFrameHandler dispatches the following events:

When the frame handler receives one of these frame events, it creates a corresponding event object and routes that object to the appropriate IFrameHandler virtual function. You can override these virtual functions to supply your own specialized processing of a frame event.

The return value from the virtual functions specifies whether the frame event is passed on for additional processing, as follows:

true
The frame event requires no additional processing. Do not pass it to another handler.
false
Pass the frame event to the next handler for additional processing, as follows:
  • If there is another handler for the frame window, pass the frame event to the next handler.
  • If this is the last handler for the frame window, call IWindow::defaultProcedure to process the frame event.

Note: Because IFrameHandler processes ICommandEvent objects, think of it as if you had more than one ICommandHandler attached to a window. If you attach an IFrameHandler to the same window as an ICommandHandler, your ICommandHandler might not be called, depending on the order in which you attach these handlers.

Portability Considerations

The AIX environment does not support the following:


IFrameHandler - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~IFrameHandler
public:
virtual ~IFrameHandler()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IFrameHandler
public:
IFrameHandler()

The default constructor accepts no parameters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

The Open Class Library dispatches events that have been sent or posted to a window to the handlers attached to that window. It does this by calling the event-dispatching function of the handler objects. An IFrameHandler object processes only frame-window-related events.


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

If a frame event is received, this function calls the appropriate virtual function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

Event-processing members handle frame-specific window events. Derived classes can override any of these virtual functions to provide specific functionality.


[view class]
activated
public:
virtual bool activated(IFrameEvent& frameEvent)

Called when the frame window is activated. By default, this function does nothing except return false. Derived classes can implement this function as follows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is called when the WM_TAKE_FOCUS message is received from the Motif Window Manager.


[view class]
calcRect
public:
virtual bool calcRect(IFrameEvent& frameEvent)

Calculates the size of either of the following:

This function accounts for the size needed for the frame's extensions and other standard components used by the frame, such as a title bar, menu bar, and system menu.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
closed
public:
virtual bool closed(IFrameEvent& frameEvent)

Called to close the frame window. This function does the following:

  1. Queries whether the frame is modal.
  2. If so, it dismisses the frame.
  3. If the frame has a client window, the handler sends an SC_CLOSE system command to the client.
  4. Calls the frame's IFrameWindow::willDestroyOnClose function.
  5. If IFrameWindow::willDestroyOnClose returns true, the handler destroys the window.

The IFrameHandler::closed function always returns true.
Note: If the frame window has a client window, you can locate the processing for closing the window in a command handler attached to either the client or frame window rather than having to override the IFrameHandler::closed function. The command handler, however, does not allow you to prevent a frame window from closing.

Exception

IAccessError The system failed to destroy the specified window. A possible cause is an invalid window handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
command
public:
virtual bool command(ICommandEvent& cmdEvent)

Called to process an application command event. If the frame has a client window, this function sends the event to the client window. This function always returns true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
deactivated
public:
virtual bool deactivated(IFrameEvent& frameEvent)

Called when the frame window loses the input focus. By default, this function does not do anything except return false. Derived classes can implement this function as follows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
draw
public:
virtual bool draw(IFrameEvent& frameEvent)

Called to draw the frame window. This function draws the separator lines between frame extensions and returns false. Derived classes can implement their own version of this function as follows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
format
public:
virtual bool format(IFrameFormatEvent& formatEvent)

Fills in an array of window position structures, one for each frame control. Use this function to do this for the frame extensions added to the frame using IFrameWindow::addExtension. Derived classes can implement this function as follows:

  1. Calling IFrameHandler::format
  2. Formatting their controls
  3. Returning true, so the standard frame controls are not formatted again

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
saved
public:
virtual bool saved(IFrameEvent& frameEvent)

Called to save the application status. By default, this function does not do anything except return false. Derived classes can implement this function as follows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Frame Extensions

Use these members to manage the frame extensions belonging to a frame window.


[view class]
numberOfExtensions
public:
virtual unsigned long numberOfExtensions( const IFrameWindow* frame ) const

Returns the number of frame extensions the specified frame window has. This number is also the number of elements in the collection returned by the frame's IFrameWindow::extensions function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
positionExtensions
protected:
virtual unsigned long positionExtensions( IFrameFormatEvent& formatEvent, unsigned long numStdControls )

Positions the frame extensions, based on the size and position of standard frame components not added through IFrameExtension objects, such as the client window, title bar, menu bar, and system menu. Call this function from within the format function after you have modified the ISWP objects for standard frame controls. Return true from format to prevent the default frame handler from positioning the frame extensions again.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


IFrameHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data