Developer

API Reference

AEECLSID_CaretWidget

Brew Release
Brew MP 1.0.2
See Also
CaretPulse ISHELL_CreateInstance AEECLSID_TextWidget Widget Events
Description
The caret widget is used to display a text marker inside other widgets to indicate where the next character will be inserted. It is most commonly used by the text widget, for instance. The caret widget exposes properties for setting its color and pulse rate (i.e. blinking caret). An OEM may further customize the appearance of all carets using the AEECLSID_CaretWidget class ID. Therefore, any widget that wishes to contain a caret widget should first try to instantiate it using a call to ISHELL_CreateInstance() with the class ID of AEECLSID_CaretWidget. If that fails, then create the default caret with CaretWidget_New().

Events:

The caret widget supports the following events:
Event                 Description 
-----                 ------------------------------------------------------------  
EVT_WDG_SETPROPERTY   Set property identified by one of the following 'wParam' parameters 
                       
                         PROP_FGCOLOR       --  Sets the color of the caret. 
                         PROP_BGCOLOR       --  Sets the background color (used for pulsing) 
                         PROP_CARETPULSE    --  Sets the pulse properties.  wParam is pointer 
                                                to a CaretPulse struct (see Properties below). 
                         PROP_ANIMATE_FLAGS --  Sets animation related flags. CaretWidget 
                                                supports setting of AF_ENABLE_EVT_STEP. 
 
EVT_WDG_GETPROPERTY  Get property identified by one of the following 'wParam' parameters 
                       
                         PROP_FGCOLOR       --  Gets the color of the caret. 
                         PROP_BGCOLOR       --  Gets the background color (used for pulsing) 
                         PROP_CARETPULSE    --  Gets the pulse properties.  wParam is pointer 
                                                to a CaretPulse struct (see Properties below). 
                         PROP_ANIMATE_FLAGS --  Gets animation related flags. 
                         PROP_OFFSETX       --  Gets horizontal offset(see Properties below). 
                         PROP_OFFSETY       --  Gets vertical offset(see Properties below). 

Properties:

The caret widget supports the following properties:
Property              Description
--------              ------------------------------------------------------------
PROP_FGCOLOR:         This property contains the color of the caret widget.

                          Property Value:  RGBVal

PROP_BGCOLOR:         This property contains the color of the background, typically
                      the same background color of the containing widget.  It is
                      the color the caret transitions to when pulsing.

                          Property Value:  RGBVal

PROP_CARETPULSE:      This property contains the pulse attributes as defined by the
                      following struct.

                          struct CaretPulse {
                              int nMin;    
                              int msTimeOn;     
                              int msFadeTime;   
                              int nFadeSteps;   
                          };        

PROP_ANIMATE_FLAGS:   This property holds the flags related to caret widget's animation.
                        
                         Property Value:  uint32

                         AF_ENABLE_EVT_STEP
                         ------------------
                         This flag allows the user to enable StepEvent to be sent through the
                         widget's ViewModel.  When caret widget animates, StepEvent will only
                         be passed to model listeners if this flag is set to true.


PROP_OFFSETX:         This property contains the horizontal offset of the caret's origin.  
                      This value can be used by TextWidget to position the caret before 
                      drawing so that it can be aligned correctly between two characters.
                      (Note that for Bi-di languages, caret may not necessarily be aligned 
                      at the center). 
                             
                         Property Value:  int
                                    
PROP_OFFSETY:         This property contains the vertical offset of the caret's origin.  
                      This value can be used by TextWidget to position the caret before 
                      drawing so that it can be aligned correctly between two characters.
                             
                         Property Value:  int

Instantiaion
A widget that wishes to contain a caret widget should first try to instantiate a CaretWidget using a call to ISHELL_CreateInstance() with the class ID of AEECLSID_CaretWidget. If that fails, then create the default caret with CaretWidget_New().
Cleanup
The CaretWidget is reference counted, so when you are done with your reference to the caret widget, you should release that reference.
Default Interface Name
  • Follow