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