minigui-docs/programming-guide/MiniGUIProgGuidePart2Chapter17.md

Other Classes

• mReferencedObj
  • Method of mReferencedObj
  • Example of mReferencedObj
• mPopMenuMgr
  • Method of mPopMenuMgr
  • Example of mPopMenuMgr
• mToolImage
  • Method of mToolImage
  • Example of mToolImage
• mToolItem
  • Type of mToolItem
  • Creation and Deletion of mToolItem
  • Other mToolItem Functions
  • Example of mToolItem

This chapter introduces some mGNCS non control classes. They are designed to provide for the control class to use.

mReferencedObj

The class encapsulate an automatic counting, allowing to control the life circle of the object through automatic quoting when the object is transferred.

The class is mainly used on some non control classes, such as the class of mToolItem and mPropMenuMgr etc.

• Inheritance relation

• mObject

  • mRefrencedObj

• Direct child classes

  • mPropMenuMgr
  • mToolItem
  • mToolImage

Method of mReferencedObj

• Quote related ports, and there are two:

   int addRef(mReferencedObj* self);
   int release(mReferencedObj* self);

addRef automatically adds 1 to the counting, and returns new counting. release will automatically reduce 1 for the counting, and returns new counting; if the counting is 0, automatically call destroy method, delete the object, including memory of the object. mReferenceObj and its derived class need to call NEW or NEWEX macro to create, because release method will call DELETE macro to release the created object. The derived class can change the release mode of the object through covering release method.

Example of mReferencedObj

The class is an abstract class, and cannot be used directly.

mPopMenuMgr

mPopMenuMgr stores the information of PropMenu, and it can:

• Create a PopMenu at any time for use

• Partial MenuItem information can be obtained to fill into MENUITEMINFO structure, and provide for the related functions of MiniGUI to use

• Inheritance relation

• mObject

  • mReferencedObj
  • mPopMenuMgr

Method of mPopMenuMgr

• Method of adding a MenuItem to mPopMenuMgr

BOOL addItem(mPropMenuMgr *self , \
                          int type, \
                          const char * str, \
                          PBITMAP bmp, \
                          int id, \
                          int state,  \
                          mPopMenuMgr *subMenu, \
                          DWORD add_data);

• Parameter

  • type – menu item type, same as the definition of MiniGUI MENUITEMINFO
    • MTF_STRING
    • MTF_BITMAP
    • MTF_BMPSTRING
    • MTF_RADIOCHECK
    • MTF_MARKCHECK
    • MTF_SEPARATOR
  • caption of str – Item, valid when type == MTF_STRING or MTF_BMPSTRING
  • Bit map of bmp – item, valid when type == MTF_BITMAP or MTF_BMPSTRING
  • id of id – item, it is a must to mark an id
  • state – item status, same as the definition of MiniGUI MENUITEMINFO
    • MFS_GRAYED
    • MFS_DISABLED
    • MFS_CHECKED
    • MFS_ENABLED
    • MFS_UNCHECKED
  • subMenu - sub menu manager
  • add_data – additional data of the user

• return: TRUE or FALSE

• Create a PopMenu, return the sentence handle of the Menu

HMENU createMenu(mPopMenuMgr *self);

• Automatically create and pop up a Pop Menu

void popMenu(mPopMenuMgr *self, mObject *owner);

• params:

  • owner points out PopMenu related object, which must be a mWidget or its child class, PopMenu will send MSG_COMMAND to owner

• return : None

• Add a segmentation bar to MenuItem

BOOL addSeparator(mPopMenuMgr * self);

• Get information of appointed MenuItem

 BOOL getMenuItem(mPopMenuMgr * self, int idx, MENUITEMINFO *pmii, BOOL byCommand);

• Fill information of appointed MenuItem to MENUITEMINFO
• params:
  • idx - index or id of menuitem
  • pmii – output parameter
  • byCommand : TRUE – idx is id of menu item; FALSE – idx is index of menu item
• return : TRUE / FALSE

Example of mPopMenuMgr

Refer to the example of mMenuButton

mToolImage

mToolImage is the class providing images to mToolItem. The class encapsulates all types of images for the convenience of the users to select

• Inheritance relation

• mObject

  • mReferencedObj
    • mToolImage

Method of mToolImage

The method of mToolImage is open, and the functions provided below can be called directly.

• Create new mToolImage object from an image object

mToolImage * ncsNewToolImage(PBITMAP pbmp, int cell_count, BOOL autoUnload, BOOL bVert);

• params

  • pbmp : source of image
  • cell_count: number of small images that pbmp contains
  • autoUnload : automatically call UnloadBitmap to delete the image
  • bVert : if arrangement of small images is vertical

• return : mToolImage pointer

• Create mToolImage object from an image file

mToolImage * ncsNewToolImageFromFile(const char *fileName, \
                    int cell_count, \
                    BOOL autoUnload, \
                    BOOL bVert);

• Release a mToolImage object

void ncsFreeToolImage(mToolImage *mti);

• Draw image of appointed position managed by mToolImage

  BOOL ncsDrawToolImageCell(mToolImage *mti, HDC hdc, int idx, const RECT *prc);

• params:
  • mti : mToolImage pointer
  • hdc : objective DC sentence handle
  • idx : small image index
  • prc: objective rectangle
• return TRUE or FALSE

For the users, mainly creating and deleting related functions are used, and draw function is used by ToolItem

Example of mToolImage

mToolItem

mToolItem is the basic class of item of mToolbar. The class and its derived class are not public. Users only need to automatically create through API provided externally.

mToolbar also delete the ones automatically managing mToolItem

Type of mToolItem

mToolItem has many child classes. In external interface, it is manifested as all kinds of types, and these definitions are as below:

enum mToolItemType{
    NCS_UNKNOWNTOOLITEM = 0,
    NCS_PUSHTOOLITEM,
    NCS_MENUTOOLITEM,
    NCS_WIDGETTOOLITEM,
    NCS_SEPARATORTOOLITEM
};

Type of a ToolItem can be detected through the function below

int ncsGetToolItemType(void *toolitem);

• Get the type of ToolItem

The function below can rapidly detect the type of an item

BOOL ncsIsPushToolItem(void *toolitem);
BOOL ncsIsMenuToolItem(void *toolitem);
BOOL ncsIsSeparatorToolItem(void *toolitem);
BOOL ncsIsWidgetToolItem(void *toolitem);

Creation and Deletion of mToolItem

• Create a PushToolItem

 void * ncsCreatePushToolItem(int id, mToolImage * img, const char * str, UINT flags);

• params:

  • img: mToolImage pointer, can be NULL
  • str: literal pointer, can be NULL, but either img or str must not be NULL
  • flags: define the relation between img and str
    • NCS_TOOLITEM_FLAG_TEXT_LEFT/NCS_TOOLITEM_FLAG_TEXT_UP, the text is on the left or top, default is right or bottom
    • NCS_TOOLITEM_FLAG_VERT, image and str are vertically arranged, and it is horizontal arrangement by default

• return: item pointer

• Create a Menu Tool Item

void * ncsCreateMenuToolItem(int id, \
                        mToolImage * img, \
                        const char * str, \
                        UINT flags, \
                        mPopMenuMgr * menu);

• Create a MenuToolItem, parameter menu is a mPopMenuMgr, and other parameters are as above

• Create a Check Tool Item

void * ncsCreateCheckToolItem(int id, \
                        mToolImage * img, \
                        const char * str, \
                        UINT flags, \
                        int state);

• Parameter is same as ncsCreatePushToolItem.

• Create a radio Tool Item

void * ncsCreateRadioToolItem(int id, mToolImage * img, const char * str, UINT flags);

• Parameter is same as ncsCreatePushToolItem. RadioToolItem is automatically grouped, starting from the first or previous separator and ending to the final or next separator, direct all RadioToolItem are mutually excluding.

• Create a ToolItem containing mWidget pointer

void * ncsCreateWidgetToolItem(mWidget * widget);

• params

  • widget : mWidget object pointer

• return : item pointer

• Create a separator

void * ncsCreateSeparatorItem(void);

• return item pointer

Other mToolItem Functions

mToolItem provides some other functions, used to operate ToolItem

• Get or set ID of ToolItem

int ncsToolItem_getId(void *self)

int ncsToolItem_setId(void *self, int id);

• If it cannot set or cannot get, return -1.

• Get or set Check status of CheckToolItem:

BOOL ncsToolItem_setCheck(void *self, int check_state);
int ncsToolItem_getCheck(void *self);

• Only valid aiming at Check/RadioToolItem. When calling ncsToolItem_getCheck for other ToolItem, unchecked status will be returned forever

• Pop up menu for MenuToolItem

 BOOL ncsToolItem_showMenu(void*self, mObject *owner);

• Only aim at menu Tool item, owner is a mWidgt* object

Example of mToolItem

---

<< Invisible Control Class | Table of Contents | Graphics Device Interfaces >>