### 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:

  - Events that activate, close, deactivate, draw, and save the frame window.
  - Command events.
  - Events used to size and position frame extensions. IFrameFormatEvent discusses this in more detail.

  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::deactivated

### IFrameHandler - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~IFrameHandler

      public:
      virtual ~IFrameHandler()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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.

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:

  - Performing their event processing
  - Returning false so other handlers can act on this event

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.

calcRect

      public:
      virtual bool calcRect(IFrameEvent& frameEvent)

  Calculates the size of either of the following:

  - The client rectangle given a frame rectangle
  - The frame rectangle given a client rectangle

  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

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

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

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:

  - Performing their event processing
  - Returning false so other handlers can act on this event

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

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:

  - Performing any additional drawing they require
  - Returning false so other handlers can act on this event

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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:

  - Saving the application status
  - Returning false so other handlers can act on this event

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Frame Extensions

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

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

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

  -     virtual ~IHandler()

  -     virtual IString asDebugInfo() const

  -     virtual IString asString() const

  -     virtual IHandler& disable()

  -     virtual IHandler& enable(bool enable = true)

  -     virtual IHandler& handleEventsFor(IWindow* window)

  -     IHandler()

  -     bool isEnabled() const

  -     virtual IHandler& stopHandlingEventsFor(IWindow* window)

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None