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