Programming Guide: Creating a Part from BaseContainer Part

# Programming Guide

## Creating a Part from BaseContainer Part

The BaseContainer part is subclassable. You should be able to develop a commercial application by subclassing BaseContainer, without writing a lot of OpenDoc-specific code. The BaseContainer part provides support for embedded frames, and allows subclassing parts to mix intrinsic contents with the embedded frmaes by using the ContentObject class to create their intrinisic content. See "The ContentObject Class" for details on how to create content objects.

### Overrides from ODPart for BaseContainer

The BaseContainer part overrides all the required methods in the ODPart class, and implements methods for the following protocols: Layout, Imaging, Activation, User events, Storage, Binding, Embedding, Clipboard, and Drag/Drop. When overriding methods inherited from BaseContainer or ODPart, the part developer should consider whether the subclassing part method should call its parent method before or after its own code, if at all. For a complete list of methods overridden by BaseContainer, refer to the parts idl file in its `src` tree in the samples directory.

### Methods Defined in BaseContainer

The following are methods defined in the BaseContainer class.

#### ActivateFrame

This method prepares the part for activation.

Signature

    ODBoolean ActivateFrame (ODFrame frame)

Parameters

frame (ODFrame) - input

  The display frame to be activated.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the frame was successfully activated.

  kODTrue | The frame was successfully activated.
  kODFalse | The frame was not successfully activated.

Remarks

The BaseContainer acquires its focus set in this method. Your part can override this method to create its own focus set, or to perform other additional actions upon part activation. For example, a Text Editor would display its cursor when it is activated.

#### CompleteMoveOperation

This method moves an embedded object from one location within the part to another.

Signature

    void CompleteMoveOperation (ODFrame containingFrame,
                                ODEventData event)

Parameters

containingFrame (ODFrame) - input

  A reference to the frame which contains the object being moved.

event (ODEventData) - input

  A platform-specific structure representing an event.

Returns

None.

Remarks

The BaseContainer moves any selected object instantiated from the ContentObject class for the referenced frame. Your part can override this method to render itself around the newly moved objects.

#### CompleteResizeOperation

This method resizes an embedded object.

Signature

    void CompleteResizeOperation (ODFrame containingFrame,
                                  ODEventData event)

Parameters

containingFrame (ODFrame) - input

  A reference to the frame which contains the object being resized.

event (ODEventData) - input

  A platform-specific structure representing an event.

Returns

None.

Remarks

The BaseContainer resizes any selected object instantiated from the ContentObject class. Your part can override this method to render itself around the newly resized objects.

#### CopySelection

This method copies the selected objects to the clipboard.

Signature

    void CopySelection (ODCloneKind cutORcopy)

Parameters

cutORcopy (ODCloneKind) - input

  The type of clone operation to be performed. << (kODCloneCopy) >>

Returns

None.

Remarks

The BaseContainer copies all selected objects instantiated from the ContentObject class to the clipboard. Your part does not need to override this method. Your part would override the WriteContents and WriteKind methods to render its own selected content to the clipboard.

#### CutSelection

This method copies the selected objects to the clipboard and deletes them from the part's content.

Signature

    void CutSelection ()

Parameters

None.

Returns

None.

Remarks

The BaseContainer copies all selected objects instantiated from the ContentObject class to the clipboard, and deletes them from its contents. Your part does not need to override this method. Your part would override the WriteContents and WriteKind methods to render its own selected content to the clipboard, and would override the DeleteSelection method to delete its selected content.

#### DeleteSelection

This method deletes the selected objects from the part's content.

Signature

    void DeleteSelection ()

Parameters

None.

Returns

None.

Remarks

The BaseContainer deletes all selected objects instantiated from the ContentObject class from its contents. Your part would override this method to delete any selected content that is not instantiated from the ContentObject class.

#### DeselectAll

This method deselects the selected objects in the part's content.

Signature

    void DeselectAll ()

Parameters

None.

Returns

None.

Remarks

The BaseContainer deselects all selected objects instantiated from the ContentObject class. Your part would override this method to deselect any selected content that is not instantiated from the ContentObject class.

#### DrawContents

This method draws the part within the area that needs updating in the specified facet.

Signature

    ODBoolean DrawContents (ODFacet facet,
                            ODShape invalidShape)

Parameters

facet (ODFacet) - input

  A reference to the facet in which the part is to draw.

invalidShape (ODShape) - input

  A reference to a shape object defining the area of the facet that needs updating, expressed in frame coordinates.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the contents were drawn successfully.

  kODTrue | The contents were drawn successfully.
  kODFalse | The contents were not drawn.

Remarks

The BaseContainer calls this method to draw its background color. Your part should override this method to draw its own intrinsic content, including any objects instantiated from the ContentObject class.

#### DrawSelectionBorder

This method draws the selection borders of any selected objects within area that needs updating in the specified facet.

Signature

    ODBoolean DrawSelectionBorder (ODFacet facet,
                                   ODShape invalidShape)

Parameters

facet (ODFacet) - input

  A reference to the facet in which the part is to draw.

invalidShape (ODShape) - input

  A reference to a shape object defining the area of the facet that needs updating, expressed in frame coordinates.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the selection border was drawn successfully.

  kODTrue | The selection border was drawn successfully.
  kODFalse | The selection border was not drawn.

Remarks

The BaseContainer calls this method to draw a selection border for all selected objects instantiated from the ContentObject class. Your part should override this method to draw a selection border for any content that is not defined in the ContentObject class, or to change the selection border used by the BaseContainer.

#### GetBackgroundColor

This method returns the background color of the part.

Signature

    COLORREF GetBackgroundColor ()

Parameters

None.

Returns

rv (COLORREF) - returns

  A platform-specific representation of the background color.

Remarks

The BaseContainer provides this method for subclassing parts to obtain the background color. Your part should not override this method.

#### GetContentObjectFromObjType

This method returns an empty content object of the specified input type.

Signature

    void GetContentObjectFromObjType (ODULong objType,
                                      ContentObject *contentObject)

Parameters

objType (ODULong) - input

  The type of content object to return.

  COBJ_BASECLASS | A generic content object.
  COBJ_FRAMECLASS | An embedded frame content object.
  <user defined> | A content object type defined by a subclass of the ContentObject class.

contentObject (ContentObject *) - input

  A reference to the content object to be returned.

Returns

None.

Remarks

The BaseContainer calls this method from ReadContents, when it internalizes data from the part's storage unit. Your part should override this method if it overrides the ContentObject class to provide its own intrinsic content. Your part should check for your content object type before calling its parent method.

#### GetDisplayFrames

This method returns a linked list of the part's display frames.

Signature

    IODLinkedList GetDisplayFrames ()

Parameters

None.

Returns

rv (IODLinkedList) - returns

  A reference to a linked list of the display frames for this part.

Remarks

The BaseContainer does not currently provide multiple display frames, but it does provide multiple display frame support. Your part should not need to override this method.

#### GetEmbeddedObjects

This method returns the linked list of content objects contained by this part.

Signature

    IODLinkedList GetEmbeddedObjects ()

Parameters

None.

Returns

rv (IODLinkedList) - returns

  A reference to a linked list of the embedded objects for this part.

Remarks

The BaseContainer maintains a list of all embedded objects instantiated from the ContentObject class. This includes embedded frames (ContentFrame objects) and any content objects instantiated from the user. Your part does not need to override this method.

#### GetMenuBar

This method returns the part's menubar.

Signature

    ODMenuBar GetMenuBar ()

Parameters

None.

Returns

rv (ODMenuBar) - returns

  A reference to this part's menubar.

Remarks

This method is provided for subclassing parts to obtain a copy of the menu bar, to enable or disable the menu items or otherwise modify it. Your part should not need to override this method. Your part would call the InstallMenuItems to add its own menu items to the BaseContainer's menu bar, and would call this method from AdjustMenus to enable or disable its own menu items.

#### GetSelectedObjects

This method returns the linked list of selected content objects contained by this part.

Signature

    IODLinkedList GetSelectedObjects ()

Parameters

None.

Returns

rv (IODLinkedList) - returns

  A reference to a linked list of the selected objects for this part.

Remarks

The BaseContainer maintains a list of all selected objects instantiated from the ContentObject class. Your part does not need to override this method.

#### HandleColorChange

This method handles a request to change the part's background color.

Signature

    ODBoolean HandleColorChange (ODFrame frame)

Parameters

frame (ODFrame) - input

  A reference to the display frame in which the background color is to be changed.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the color change was handled successfully.

  kODTrue | The color change was handled successfully.
  kODFalse | The background color was not changed.

Remarks

The BaseContainer calls this method in response to a menu or scripting event. Your part should override this method to restrict the background color change function or to change its intrinsic content in conjunction with the color change.

#### HandleMenuEvent

This method attempts to handle the specified menu event.

Signature

    ODBoolean HandleMenuEvent (ODFrame frame,
                               ODEventData event)

Parameters

frame (ODFrame) - input

  A reference to the frame which owned the menu focus when the menu event occurred.

event (ODEventData) - input

  A platform-specific structure representing an event.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the menu event was handled successfully.

  kODTrue | The menu event was handled successfully.
  kODFalse | The menu event was not handled.

Remarks

The BaseContainer handles all standard menu events to be handled by parts. It also handles the menu events for the menu items it adds to the menu bar. Your part should override this method if it provides additional menu events to be handled.

#### HandleMouseClick

This method processes a mouse click event.

Signature

    ODBoolean HandleMouseClick (ODEventData event,
                                ODFrame frame,
                                ODFacet facet,
                                ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse click occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse click occurred.

eventInfo (ODEventInfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer handles the mouse clicks related to operations on its embedded content objects. Your part should override this method to provide any additional behavior for mouse clicks.

#### HandleMouseDown

This method interprets a mouse button down event.

Signature

    ODBoolean HandleMouseDown (ODEventData event,
                               ODFrame frame,
                               ODFacet facet,
                               ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse button down occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse button down occurred.

eventInfo (ODEventInfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer interprets the mouse down event based on platform specific parameters. Your part should not override this method.

#### HandleMouseMotionLBDown

This method handles a mouse left-button down event.

Signature

    ODBoolean HandleMouseMotionLBDown (ODEventData event,
                                       ODFrame frame,
                                       ODFacet facet,
                                       ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse event occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse event originated.

eventInfo (ODEventInfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer handles the mouse left-button down event for operations on its embedded content objects. Your part should override this method to provide any additional behavior for mouse left-button down events.

#### HandleMouseMotionEnd

This method handles a mouse motion end event.

Signature

    ODBoolean HandleMouseMotionEnd (ODEventData event,
                                    ODFrame frame,
                                    ODFacet facet,
                                    ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse event occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse motion ended.

eventInfo (ODEventInfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer handles the mouse motion end event for operations on its embedded content objects. Your part should override this method to provide any additional behavior for mouse motion end events.

#### HandleMouseMotionStart

This method handles a mouse motion start event.

Signature

    ODBoolean HandleMouseMotionStart (ODEventData event,
                                      ODFrame frame,
                                      ODFacet facet,
                                      ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse event occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse motion was started.

eventInfo (ODEventinfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer handles the mouse motion start event for operations on its embedded content objects. Your part should override this method to provide any additional behavior for mouse motion start events.

#### HandleMouseMove

This method interprets a mouse move event.

Signature

    ODBoolean HandleMouseMove (ODEventData event,
                               ODFrame frame,
                               ODFacet facet,
                               ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse event occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse was moved.

eventInfo (ODEventInfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer determines if the mouse move event is associated with a motion start or left button down. The HandleMouseMotionStart or HandleMouseMotionLBDown methods may be called from this method. Your part should not override this method.

#### HandleMouseUp

This method interprets a mouse button up event.

Signature

    ODBoolean HandleMouseUp (ODEventData event,
                             ODFrame frame,
                             ODFacet facet,
                             ODEventInfo eventInfo)

Parameters

event (ODEventData) - input

  A platform-specific structure representing an event.

frame (ODFrame) - input

  A reference to the display frame which owned the mouse focus when the mouse event occurred.

facet (ODFacet) - input

  A reference to the facet in which the mouse up occurred.

eventInfo (ODEventInfo) - input

  A platform-specific structure containing context-.specific event information.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the mouse event was handled successfully.

  kODTrue | The mouse event was handled.
  kODFalse | The mouse event was not handled.

Remarks

The BaseContainer determines if the mouse up event is associated with a mouse click or a mouse down/move operation. The HandleMouseClick HandleMouseMotionEnd methods may be called from this method. Your part should not override this method.

#### Initialize

This method initializes the part.

Signature

    void Initialize (ODPart partWrapper)

Parameters

partWrapper (ODPart) - input

  A reference to the part wrapper representing this part.

Returns

None.

Remarks

The BaseContainer calls this method from both InitPart and InitPartFromStorage to initialize its instance variables and to gather data from OpenDoc. Your part should override this method to initialize its own instance variables. The partWrapper parameter represents a delegator object which OpenDoc uses in lieu of a direct pointer to your ODPart object. Your part editor should save this parameter. Whenever an OpenDoc function requires a part editor to pass in an ODPart* representing the part, the part editor must pass in its partWrapper instead of passing in somSelf.

#### InstallMenuItems

This method adds the part-specific menu items to the input menubar.

Signature

    void InstallMenuItems (ODMenuBar menuBar)

Parameters

menuBar (ODMenuBar) - input

  A reference to the menubar to which the new menu items will be added.

Returns

None.

Remarks

The BaseContainer calls this method to add its own menu items to the OpenDoc base menu bar. Your part should override this method to add its own menu items to the menu bar.

#### MakeWindow

This method creates a window for the input source frame.

Signature

    ODWindow  MakeWindow (ODFrame frame)

Parameters

frame (ODFrame) - input

  A reference to the source frame to be displayed in the window.

Returns

rv (ODWindow) - returns

  A reference to the newly created window.

Remarks

The BaseContainer calls this method in response to the Open command. Your part should not override this method.

#### MoveSelectionToBack

This method moves the selected objects to the back of the Z-order.

Signature

    void MoveSelectionToBack ()

Parameters

None.

Returns

None.

Remarks

The BaseContainer moves all selected objects instantiated from the ContentObject class to the back of the Z-order. Your part would override this method to adjust the Z-order of any selected content that is not instantiated from the ContentObject class. However, the order of the parts intrinsic content will be maintained separately from the BaseContainer's content objects.

#### MoveSelectionToFront

This method moves the selected objects to the front of the Z-order.

Signature

    void MoveSelectionToFront ()

Parameters

None.

Returns

None.

Remarks

The BaseContainer moves all selected objects instantiated from the ContentObject class to the front of the Z-order. Your part would override this method to adjust the Z-order of any selected content that is not instantiated from the ContentObject class. However, the order of the parts intrinsic content will be maintained separately from the BaseContainer's content objects.

#### PasteSelection

This method pastes the objects from the clipboard to this part.

Signature

    void PasteSelection (ODFacet facet,
                         ODPoint toWhere)

Parameters

facet (ODFacet) - input

  A reference to the facet in which the data being pasted is to be displayed.

toWhere (ODPoint) - input

  The location within the facet at which the data should be pasted.

Returns

None.

Remarks

The BaseContainer pastes all selected objects instantiated from the ContentObject class at the position indicated by the input parameters. Your part does not need to override this method. Your part would override the ReadContents and ReadKind methods to read its own intrinsic content from the clipboard storage unit.

#### PasteSelectionAs

This method currently calls PasteSelection, as BaseContainer does not provide linking support.

Signature

    void PasteSelectionAs (ODFacet facet,
                           ODPoint toWhere)

Parameters

facet (ODFacet) - input

  A reference to the facet in which the data being pasted is to be displayed.

toWhere (ODPoint) - input

  The location within the facet at which the data should be pasted.

Returns

None.

Remarks

The BaseContainer does not support linking, so the PasteSelectionAs method simply calls PasteSelection. If your part provides linking support, it should override this method to show the PasteAs dialog and process the user input in your part's linking implementation.

#### ReadContents

This method reads the content objects from the input storage unit.

Signature

    void ReadContents (ODStorageUnit fromSU,
                       BCCloneInfo *cloneInfo,
                       ODULong readKind)

Parameters

fromSu (ODStorageUnit) - input

  A reference to the storageUnit containing the part's contents.

cloneInfo (BCCloneInfo *) - input

  A data structure containing information about how the data in the storage unit was cloned.

readKind (ODULong) - input

  The type of cloning operation to perform on the storage unit.

  EXTERNALIZE | Write the part's contents out to the storage unit.
  INTERNALIZE | Read the part's contents in from the storage unit.
  CLONEALL | Clone the part's contents and embedded frames to the storage unit.
  CLONESELECTED | Clone only the part's selected contents and selected embedded frames to the storage unit.

Returns

None.

Remarks

The BaseContainer reads the content objects in from the storage unit. Your part should override this method if it provides its own intrinsic content that is not instantiated from the ContentObject class.

#### ReadKindInfo

This method reads the part kind from the input storage unit.

Signature

    ODBoolean ReadKindInfo (ODStorageUnit fromSU)

Parameters

fromSU (ODStorageUnit) - input

  A reference to the storageUnit containing the part kind.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the read operation completed successfully.

  kODTrue | The part kind information was read successfully.
  kODFalse | The part kind information was not read.

Remarks

The BaseContainer reads the BaseContainer part kind from the storage unit. Your part should override this method if it provides its own part kind in addition to or instead of the BaseContainer's part kind.

#### SelectAll

This method selects all unselected objects in the part's content.

Signature

    void SelectAll()

Parameters

None.

Returns

None.

Remarks

The BaseContainer selects all unselected objects instantiated from the ContentObject class. Your part would override this method to select any unselected content that is not instantiated from the ContentObject class.

#### SelectContentObject

This method selects the specified contentObject.

Signature

    void SelectContentObject (ContentObject contentObject)

Parameters

contentObject (ContentObject) - input

  A reference to the content object to be selected.

Returns

None.

Remarks

The BaseContainer calls this method to select its embedded frame content objects. Your part should override this method to provide selection code for its own content objects. Your part should also call this method when a selection action on one or more of its objects has occurred.

#### SetBackgroundColor

This method sets the background color to the specified color.

Signature

    void SetBackgroundColor (COLORREF color)

Parameters

color (COLORREF) - input

  A platform-specific definition of the new background color.

Returns

None.

Remarks

The BaseContainer provides this method for subclassing parts to set the background color to a specific color rather than through the color dialog. Your part should not override this method.

#### WriteContents

This method writes the part's content objects to the specified storage unit.

Signature

    void WriteContents (ODStorageUnit toSU,
                        BCCloneInfo *cloneInfo,
                        ODULong writeKind)

Parameters

toSu (ODStorageUnit) - input

  A reference to the storageUnit to which the part's contents will be written.

cloneInfo (BCCloneInfo *) - input

  A data structure containing information about to clone the data to the storage unit.

writeKind (ODUlong) - input

  The type of cloning operation to perform on the storage unit.

  EXTERNALIZE | Write the part's contents out to the storage unit.
  INTERNALIZE | Read the part's contents in from the storage unit.
  CLONEALL | Clone the part's contents and embedded frames to the storage unit.
  CLONESELECTED | Clone only the part's selected contents and selected embedded frames to the storage unit.

Returns

None.

Remarks

The BaseContainer writes its content objects out to the storage unit. Your part should override this method if it provides its own intrinsic content that is not instantiated from the ContentObject class.

#### WriteIconToSU

This method writes the part's icon to the specified storage unit.

Signature

    void WriteIconToSU (ODStorageUnit toSU)

Parameters

toSU (ODStorageUnit) - input

  A reference to the storage unit to which the part icon should be written.

Returns

None.

Remarks

The BaseContainer writes its own icon to the specified storage unit as part of the WriteContents method. Your part should override WriteIconToSU if it has a different icon from that of the BaseContainer.

#### WriteKindInfo

This method writes the part's kind out to the specified storage unit.

Signature

    void WriteKindInfo (ODStorageUnit toSU)

Parameters

toSU (ODstorageUnit) - input

  A reference to the storage unit to which the part kind should be written.

Returns

None.

Remarks

The BaseContainer writes the BaseContainer part kind to the storage unit. Your part should override this method if it provides its own part kind in addition to or instead of the BaseContainer's part kind.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]