interface/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        editors.h
   3 // Purpose:     interface of wxPropertyGrid editors
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 // -----------------------------------------------------------------------
  10
  11 /**
  12     @class wxPGEditor
  13
  14     Base class for custom wxPropertyGrid editors.
  15
  16     @remarks
  17     - Names of built-in property editors are: TextCtrl, Choice,
  18       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
  19       editors include SpinCtrl and DatePickerCtrl, but using them requires
  20       calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
  21
  22     - Pointer to built-in editor is available as wxPGEditor_EditorName
  23       (eg. wxPGEditor_TextCtrl).
  24
  25     - Before you start using new editor you just created, you need to register
  26       it using static function
  27       wxPropertyGrid::RegisterEditorClass(), with code like this:
  28         @code
  29             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  30         @endcode
  31       After that, wxPropertyGrid will take ownership of the given object, but
  32       you should still store editorPointer somewhere, so you can pass it to
  33       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  34
  35     @library{wxpropgrid}
  36     @category{propgrid}
  37 */
  38 class wxPGEditor : public wxObject
  39 {
  40 public:
  41
  42     /** Constructor. */
  43     wxPGEditor()
  44         : wxObject()
  45     {
  46         m_clientData = NULL;
  47     }
  48
  49     /** Destructor. */
  50     virtual ~wxPGEditor();
  51
  52     /**
  53         Returns pointer to the name of the editor. For example,
  54         wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access
  55         your custom editor by string name, then you do not need to implement
  56         this function.
  57     */
  58     virtual wxString GetName() const;
  59
  60     /**
  61         Instantiates editor controls.
  62
  63         @param propgrid
  64             wxPropertyGrid to which the property belongs (use as parent for control).
  65
  66         @param property
  67             Property for which this method is called.
  68
  69         @param pos
  70             Position, inside wxPropertyGrid, to create control(s) to.
  71
  72         @param size
  73             Initial size for control(s).
  74
  75         @remarks
  76         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  77           shall use wxPG_SUBID2.
  78         - Implementation shoud connect all necessary events to the
  79           wxPropertyGrid::OnCustomEditorEvent. For Example:
  80             @code
  81                 // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor
  82                 // control to the OnEvent.
  83                 control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
  84                                  wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent),
  85                                  NULL, propgrid);
  86             @endcode
  87           OnCustomEditorEvent will then forward events, first to
  88           wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent().
  89     */
  90     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
  91                                            wxPGProperty* property,
  92                                            const wxPoint& pos,
  93                                            const wxSize& size ) const = 0;
  94
  95     /** Loads value from property to the control. */
  96     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  97
  98     /**
  99         Draws value for given property.
 100     */
 101     virtual void DrawValue( wxDC& dc, const wxRect& rect,
 102                             wxPGProperty* property, const wxString& text ) const;
 103
 104     /**
 105         Handles events. Returns @true if value in control was modified
 106         (see wxPGProperty::OnEvent() for more information).
 107
 108         @remarks wxPropertyGrid will automatically unfocus the editor when
 109                 wxEVT_COMMAND_TEXT_ENTER is received and when it results in
 110                 property value being modified. This happens regardless of
 111                 editor type (ie. behavior is same for any wxTextCtrl and
 112                 wxComboBox based editor).
 113     */
 114     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 115         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 116
 117     /**
 118         Returns value from control, via parameter 'variant'.
 119         Usually ends up calling property's StringToValue() or IntToValue().
 120         Returns @true if value was different.
 121     */
 122     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
 123         wxWindow* ctrl ) const;
 124
 125     /** Sets value in control to unspecified. */
 126     virtual void SetValueToUnspecified( wxPGProperty* property,
 127         wxWindow* ctrl ) const = 0;
 128
 129     /** Sets control's value specifically from string. */
 130     virtual void SetControlStringValue( wxPGProperty* property,
 131         wxWindow* ctrl, const wxString& txt ) const;
 132
 133     /** Sets control's value specifically from int (applies to choice etc.). */
 134     virtual void SetControlIntValue( wxPGProperty* property,
 135         wxWindow* ctrl, int value ) const;
 136
 137     /**
 138         Inserts item to existing control. Index -1 means end of list.
 139         Default implementation does nothing. Returns index of item added.
 140     */
 141     virtual int InsertItem( wxWindow* ctrl, const wxString& label,
 142         int index ) const;
 143
 144     /**
 145         Deletes item from existing control.
 146         Default implementation does nothing.
 147     */
 148     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 149
 150     /**
 151         Extra processing when control gains focus. For example, wxTextCtrl
 152         based controls should select all text.
 153     */
 154     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 155
 156     /**
 157         Returns @true if control itself can contain the custom image. Default
 158         implementation returns @false.
 159     */
 160     virtual bool CanContainCustomImage() const;
 161 };
 162
 163 // -----------------------------------------------------------------------
 164
 165 /**
 166     @class wxPGMultiButton
 167
 168     This class can be used to have multiple buttons in a property editor.
 169     You will need to create a new property editor class, override CreateControls,
 170     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 171
 172     For instance, here we add three buttons to a TextCtrl editor:
 173
 174     @code
 175
 176     #include <wx/propgrid/editors.h>
 177
 178     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 179     {
 180         DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)
 181     public:
 182         wxSampleMultiButtonEditor() {}
 183         virtual ~wxSampleMultiButtonEditor() {}
 184
 185         virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
 186
 187         virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
 188                                                wxPGProperty* property,
 189                                                const wxPoint& pos,
 190                                                const wxSize& sz ) const;
 191         virtual bool OnEvent( wxPropertyGrid* propGrid,
 192                               wxPGProperty* property,
 193                               wxWindow* ctrl,
 194                               wxEvent& event ) const;
 195     };
 196
 197     IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor)
 198
 199     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
 200                                                               wxPGProperty* property,
 201                                                               const wxPoint& pos,
 202                                                               const wxSize& sz ) const
 203     {
 204         // Create and populate buttons-subwindow
 205         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 206
 207         // Add two regular buttons
 208         buttons->Add( "..." );
 209         buttons->Add( "A" );
 210         // Add a bitmap button
 211         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 212
 213         // Create the 'primary' editor control (textctrl in this case)
 214         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 215                                  ( propGrid, property, pos,
 216                                    buttons->GetPrimarySize() );
 217
 218         // Finally, move buttons-subwindow to correct position and make sure
 219         // returned wxPGWindowList contains our custom button list.
 220         buttons->Finalize(propGrid, pos);
 221
 222         wndList.SetSecondary( buttons );
 223         return wndList;
 224     }
 225
 226     bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
 227                                              wxPGProperty* property,
 228                                              wxWindow* ctrl,
 229                                              wxEvent& event ) const
 230     {
 231         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 232         {
 233             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 234
 235             if ( event.GetId() == buttons->GetButtonId(0) )
 236             {
 237                 // Do something when first button is pressed
 238                 return true;
 239             }
 240             if ( event.GetId() == buttons->GetButtonId(1) )
 241             {
 242                 // Do something when second button is pressed
 243                 return true;
 244             }
 245             if ( event.GetId() == buttons->GetButtonId(2) )
 246             {
 247                 // Do something when third button is pressed
 248                 return true;
 249             }
 250         }
 251         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 252     }
 253
 254     @endcode
 255
 256     Further to use this editor, code like this can be used:
 257
 258     @code
 259
 260         // Register editor class - needs only to be called once
 261         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
 262         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
 263
 264         // Insert the property that will have multiple buttons
 265         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 266
 267         // Change property to use editor created in the previous code segment
 268         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 269
 270     @endcode
 271
 272     @library{wxpropgrid}
 273     @category{propgrid}
 274 */
 275 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 276 {
 277 public:
 278
 279     /**
 280         Constructor.
 281     */
 282     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 283
 284     /**
 285         Destructor.
 286     */
 287     virtual ~wxPGMultiButton() { }
 288
 289     /**
 290         Adds new button, with given label.
 291     */
 292     void Add( const wxString& label, int id = -2 );
 293
 294     /**
 295         Adds new bitmap button.
 296     */
 297     void Add( const wxBitmap& bitmap, int id = -2 );
 298
 299     /**
 300         Call this in CreateControls() of your custom editor class
 301         after all buttons have been added.
 302
 303         @param propGrid
 304             wxPropertyGrid given in CreateControls().
 305
 306         @param pos
 307             wxPoint given in CreateControls().
 308     */
 309     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 310
 311     /**
 312         Returns pointer to one of the buttons.
 313     */
 314     wxWindow* GetButton( unsigned int i );
 315
 316     /**
 317         Returns Id of one of the buttons. This is utility function to be
 318         used in event handlers.
 319     */
 320     int GetButtonId( unsigned int i ) const;
 321
 322     /**
 323         Returns number of buttons.
 324     */
 325     unsigned int GetCount();
 326
 327     /**
 328         Returns size of primary editor control, as appropriately
 329         reduced by number of buttons present.
 330     */
 331     wxSize GetPrimarySize() const;
 332 };
 333
 334 // -----------------------------------------------------------------------