Programming Guide: Creating a Part from SimplePart

# Programming Guide

## Creating a Part from SimplePart

The Simple Part sample component demonstrates the OpenDoc functionality for non-containing parts. It also provides sample code to draw the four different viewtypes, frame, large icon, small icon, and thumbnail. Your part can subclass from the Simple Part to provide an OpenDoc application which can be embedded in other OpenDoc components.

### SimplePart Attributes

The following attributes are public in the SimplePart class. They can be accessed by the "set" and "get" methods provided by SOM for the attributes.

hSmallIcon (HIconView) | A reference to the small icon resource.
hLargeIcon (HIconView) | A reference to the large icon resource.
hThumbnail (HThumbView) | A reference to the thumbnail resource.
hResModule (HResModule) | A reference to the resource module which contains the icon or thumbnail resources.

### Overrides from ODPart for SimplePart

The Simple part overrides all the required methods in the ODPart class, and implements methods for the following protocols: Activation, User Events, and Imaging. When overriding methods inherited from SimplePart 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 SimplePart, refer to the parts idl file in its `src` tree in the samples directory.

### Methods Defined in SimplePart Class

The following are methods defined in the SimplePart class.

#### AdjustViewTypeShapes

This method sets the used and active shape for the current view type (frame, thumbnail, large icon, or small icon).

Signature

    void AdjustViewTypeShapes (ODFrame frame)

Parameters

frame (ODFrame) - input

  The display frame for which the used shape should be adjusted.

Returns

None.

Remarks

The SimplePart calls this method whenever its viewtype is changed, to set the used shape of its frame and the active shape of its frame's facets to correspond to the new viewtype. Your part would override this method to set a different active/used shape from that which SimplePart uses.

#### Activate

This method activates the input facet.

Signature

    ODBoolean Activate (ODFacet facet)

Parameters

facet (ODFacet) - input

  The facet to be activated.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the facet was successfully activated.

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

Remarks

The SimplePart calls ActivateFrame from this method. Your part should not need to override this method.

#### 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 SimplePart 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.

#### CommonInit

This method initializes the part.

Signature

    void CommonInit (ODPart partWrapper)

Parameters

partWrapper (ODPart) - input

  A reference to the part wrapper representing this part.

Returns

None.

Remarks

The SimplePart 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.

#### CreateFramePartInfo

This method creates the PartInfo record to associate with a part's display frame.

Signature

    PartInfoRec * CreateFramePartInfo ()

Parameters

None.

Returns

rv (PartInfoRec) - returns

  A reference to the newly created PartInfo record, which contains information associated with a particular frame.

Remarks

The SimplePart calls this method to create the PartInfo record for a display frame. Your part should override this method to add any additional information to the record. The pOther field is available for a subclassing part to use for its own display frame information.

#### CreateIcons

This method creates the large and small icons for the part.

Signature

    void CreateIcons ()

Parameters

None.

Returns

None.

Remarks

SimplePart calls this method to create its icons when it is displayed with a large or small icon viewtype. Your part should override this method if it wants to create its own icons.

#### DeleteFramePartInfo

This method deallocates the PartInfo record associated with a part's display frame.

Signature

    void DeleteFramePartInfo (PartInfoRec *pInfo)

Parameters

pInfo (PartInfoRec *) - input

  A reference to the PartInfo record to be deleted.

Returns

None.

Remarks

The SimplePart calls this method to delete the PartInfo record for a display frame. Your part should override this method if it has allocated any additional memory for its display frame's PartInfo records.

#### DrawFrame

This method draws the part's content for the frame viewtype within the area that needs updating in the specified facet.

Signature

    void DrawFrame (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

None.

Remarks

The SimplePart calls this method to render its background. Your part should override this method to draw its own intrinsic content.

#### DrawIcon

This method draws the part's large or small icon within the area that needs updating in the specified facet.

Signature

    void DrawIcon (ODFacet facet,
                   ODShape invalidShape,
                   ViewTypeEnum viewType)

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.

viewType (ViewTypeEnum) - input

  An enumerated value of the viewType to render.

  FrameView | Frame view type
  LargeIconView | Large-icon (standard) view type
  SmallIconView | Small-icon view type
  ThumbnailView | Thumbnail view type

Returns

None.

Remarks

The SimplePart calls this method to draw its large or small icons. Your part would override this method if its icons were in a different format than the SimplePart icons, and would therefore have to be drawn differently.

#### FreeResModule

This method frees the resource module from which the icons were loaded.

Signature

    void FreeResModule ()

Parameters

None.

Returns

None.

Remarks

SimplePart calls this method from somUnit to free its resource module. Your part should override this method if did not load a resource module when it created its icons.

#### GetMenuBar

This method returns the SimplePart'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 InstallMenus to add its own menu items to the SimplePart's menu bar, and would call this method from AdjustMenus to enable or disable its own menu items.

#### GetPopupMenu

This method returns the SimplePart's pop-up menu.

Signature

    ODPopup GetPopupMenu ()

Parameters

None.

Returns

rv (ODPopup) - returns

  A reference to this part's pop-up menu.

Remarks

This method is provided for subclassing parts to obtain a copy of the pop-up menu, 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 InstallMenus to add its own menu items to the SimplePart's pop-up menu, and would call this method from AdjustMenus to enable or disable its own menu items.

#### 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 successfully handled.

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

Remarks

The SimplePart handles the View In Window menu event and the "View As" events from presentation page of the Document Properties notebook. Your part should override this method to handle standard OpenDoc menu events to be handled by parts, or to handle events for menu items it adds.

#### InstallMenus

This method adds the part-specific menu items to the part's menubar and pop-up menu.

Signature

    void InstallMenus ()

Parameters

None.

Returns

None.

Remarks

The SimplePart calls this method to add its own menu items to the OpenDoc base menubar and pop-up menu. Your part should override this method to add its own menu items to the menu bar or pop-up menu.

#### LoadIconsFromModule

This method loads the large and small icons from a resource module into the _hSmallIcon and _hLargeIcon instance variables.

Signature

    void LoadIconsFromModule (string moduleName,
                              long iconID)

Parameters

moduleName (string) - input

  The name of the resource module which contains the icons to be loaded.

iconID (long) - input

  The id of the Icon to load from the resource module.

Returns

None.

Remarks

The SimplePart calls this method to load its large and small icons. It will set the _hResModule, _hSmallIcon and _hLargeIcon instance variables in the process. Your part would call this method to load its icons from its own resource module. Your part should not need to override this method.

#### SetViewTypeRect

This method determines the placement of the part's icon or thumbnail view within its display frame's used shape.

Signature

    void SetViewTypeRect (ViewTypeEnum viewType,
                          ODRect rect)

Parameters

viewType (ViewTypeEnum) - input

  An enumerated value indicating the viewType for which for which the rectangle should be set.

  LargeIconView | Large icon (standard) view type.
  SmallIconView | Small icon view type.
  ThumbnailView | Very small, thumbnail view type.

rect (ODRect) - input/output

  The bounding box for the part's display frame on input, the usedShape for the specified viewType.

Returns

None.

Remarks

SimplePart calls this method to determine where, within its frame, the icon or thumbnail view will be rendered. This method sets the frame's used shape and its facets' active shapes to correspond to the size of the specified viewType. Your part would override this method to modify the placement of its icon or thumbnail view within its display frame, or to modify the usedShape or activeShape for a viewType.

#### 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 SimplePart calls this method in response to the Open command. Your part should not need to override this method.

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