docs/latex/wx/odcbox.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        odcbox.tex
   3 %% Purpose:     wxOwnerDrawnComboBox docs
   4 %% Author:      Jaakko Salli
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Jaakko Salli
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxOwnerDrawnComboBox}}\label{wxownerdrawncombobox}
  13
  14 wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
  15 In essence, it is a \helpref{wxComboCtrl}{wxcomboctrl} with
  16 \helpref{wxVListBox}{wxvlistbox} popup and \helpref{wxControlWithItems}{wxcontrolwithitems}
  17 interface.
  18
  19 Implementing item drawing and measuring is similar to \helpref{wxVListBox}{wxvlistbox}.
  20 Application needs to subclass wxOwnerDrawnComboBox and implement
  21 \helpref{OnDrawItem()}{wxownerdrawncomboboxondrawitem}, \helpref{OnMeasureItem()}{wxownerdrawncomboboxonmeasureitem}
  22 and \helpref{OnMeasureItemWidth()}{wxownerdrawncomboboxonmeasureitemwidth}.
  23
  24
  25 \wxheading{Derived from}
  26
  27 \helpref{wxComboCtrl}{wxcomboctrl}\\
  28 \helpref{wxControl}{wxcontrol}\\
  29 \helpref{wxWindow}{wxwindow}\\
  30 \helpref{wxEvtHandler}{wxevthandler}\\
  31 \helpref{wxObject}{wxobject}
  32
  33 \wxheading{Include files}
  34
  35 <wx/odcombo.h>
  36
  37 \wxheading{Library}
  38
  39 \helpref{wxAdv}{librarieslist}
  40
  41 \wxheading{Window styles}
  42
  43 \begin{twocollist}\itemsep=0pt
  44 \twocolitem{\windowstyle{wxODCB\_DCLICK\_CYCLES}}{Double-clicking cycles item
  45 if wxCB\_READONLY is also used. Synonymous with wxCC\_SPECIAL\_DCLICK.}
  46 \twocolitem{\windowstyle{wxODCB\_STD\_CONTROL\_PAINT}}{Control itself is not
  47 custom painted using OnDrawItem. Even if this style is not used, writable
  48 wxOwnerDrawnComboBox is never custom painted unless SetCustomPaintWidth is
  49 called.}
  50 \end{twocollist}
  51
  52 See also \helpref{wxComboCtrl window styles}{wxcomboctrl} and
  53 base \helpref{window styles overview}{windowstyles}.
  54
  55 \wxheading{Event handling}
  56
  57 \twocolwidtha{7cm}
  58 \begin{twocollist}\itemsep=0pt
  59 \twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
  60 when an item on the list is selected. Note that calling
  61 \helpref{GetValue}{wxcomboctrlgetvalue} returns the new value of selection.}
  62 \end{twocollist}
  63
  64 See also events emitted by \helpref{wxComboCtrl}{wxcomboctrl}.
  65
  66 \wxheading{See also}
  67
  68 \helpref{wxComboCtrl}{wxcomboctrl}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxVListBox}{wxvlistbox},
  69 \rtfsp\helpref{wxCommandEvent}{wxcommandevent}
  70
  71
  72 \latexignore{\rtfignore{\wxheading{Members}}}
  73
  74
  75 \membersection{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}\label{wxownerdrawncomboboxctor}
  76
  77 \func{}{wxOwnerDrawnComboBox}{\void}
  78
  79 Default constructor.
  80
  81 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  82 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  83 \param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
  84 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  85
  86 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  87 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
  88 \param{const wxArrayString\& }{choices},\rtfsp
  89 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  90
  91 Constructor, creating and showing a owner-drawn combobox.
  92
  93 \wxheading{Parameters}
  94
  95 \docparam{parent}{Parent window. Must not be NULL.}
  96
  97 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  98
  99 \docparam{value}{Initial selection string. An empty string indicates no selection.}
 100
 101 \docparam{pos}{Window position.}
 102
 103 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 104 appropriately.}
 105
 106 \docparam{n}{Number of strings with which to initialise the control.}
 107
 108 \docparam{choices}{An array of strings with which to initialise the control.}
 109
 110 \docparam{style}{Window style. See \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}.}
 111
 112 \docparam{validator}{Window validator.}
 113
 114 \docparam{name}{Window name.}
 115
 116 \wxheading{See also}
 117
 118 \helpref{wxOwnerDrawnComboBox::Create}{wxownerdrawncomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 119
 120
 121 \membersection{wxOwnerDrawnComboBox::\destruct{wxOwnerDrawnComboBox}}\label{wxownerdrawncomboboxdtor}
 122
 123 \func{}{\destruct{wxOwnerDrawnComboBox}}{\void}
 124
 125 Destructor, destroying the owner-drawn combobox.
 126
 127
 128 \membersection{wxOwnerDrawnComboBox::Create}\label{wxownerdrawncomboboxcreate}
 129
 130 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 131 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 132 \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
 133 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 134
 135 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 136 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
 137 \param{const wxArrayString\& }{choices},\rtfsp
 138 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 139
 140 Creates the combobox for two-step construction. Derived classes
 141 should call or replace this function. See
 142 \helpref{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}{wxownerdrawncomboboxctor}\rtfsp
 143 for further details.
 144
 145
 146 \membersection{wxOwnerDrawnComboBox::GetWidestItem}\label{wxownerdrawncomboboxgetwidestitem}
 147
 148 \constfunc{int}{GetWidestItem}{\void}
 149
 150 Returns index to the widest item in the list.
 151
 152
 153 \membersection{wxOwnerDrawnComboBox::GetWidestItemWidth}\label{wxownerdrawncomboboxgetwidestitemwidth}
 154
 155 \constfunc{int}{GetWidestItemWidth}{\void}
 156
 157 Returns width of the widest item in the list.
 158
 159
 160 \membersection{wxOwnerDrawnComboBox::OnDrawBackground}\label{wxownerdrawncomboboxondrawbackground}
 161
 162 \constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 163
 164 This method is used to draw the items background and, maybe, a border around it.
 165
 166 The base class version implements a reasonable default behaviour which consists
 167 in drawing the selected item with the standard background colour and drawing a
 168 border around the item if it is either selected or current.
 169
 170 \wxheading{Remarks}
 171
 172 \arg{flags} has the same meaning as with \helpref{OnDrawItem}{wxownerdrawncomboboxondrawitem}.
 173
 174
 175 \membersection{wxOwnerDrawnComboBox::OnDrawItem}\label{wxownerdrawncomboboxondrawitem}
 176
 177 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 178
 179 The derived class may implement this function to actually draw the item
 180 with the given index on the provided DC. If function is not implemented,
 181 the item text is simply drawn, as if the control was a normal combobox.
 182
 183 \wxheading{Parameters}
 184
 185 \docparam{dc}{The device context to use for drawing}
 186
 187 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 188 region is set to this rectangle before calling this function)}
 189
 190 \docparam{item}{The index of the item to be drawn}
 191
 192 \docparam{flags}{Combines any of the following flag values:}
 193
 194 \twocolwidtha{7cm}%
 195 \begin{twocollist}\itemsep=0pt
 196 \twocolitem{{\tt wxODCB\_PAINTING\_CONTROL}}{Combo control is being
 197 painted, instead of a list item. Argument item may be wxNOT\_FOUND in this
 198 case.}
 199 \twocolitem{{\tt wxODCB\_PAINTING\_SELECTED}}{An item with selection
 200 background is being painted. DC text colour should already be correct.}
 201 \end{twocollist}
 202
 203
 204 \membersection{wxOwnerDrawnComboBox::OnMeasureItem}\label{wxownerdrawncomboboxonmeasureitem}
 205
 206 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{item}}
 207
 208 The derived class may implement this method to return the height of the
 209 specified item (in pixels).
 210
 211 The default implementation returns text height, as if this control was
 212 a normal combobox.
 213
 214
 215 \membersection{wxOwnerDrawnComboBox::OnMeasureItemWidth}\label{wxownerdrawncomboboxonmeasureitemwidth}
 216
 217 \constfunc{wxCoord}{OnMeasureItemWidth}{\param{size\_t }{item}}
 218
 219 The derived class may implement this method to return the width of the
 220 specified item (in pixels). If -1 is returned, then the item text width
 221 is used.
 222
 223 The default implementation returns -1.
 224