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