thr3ads.net - wxruby development - [Wxruby-development] [766] trunk/wxruby2: Added item_data aliases for client_data functions, update doc & tests; [Dec 2006]

If this information is useful, please help other people find it:
Share via:
nobody at rubyforge.org
2006-Dec-01 17:40 UTC
[Wxruby-development] [766] trunk/wxruby2: Added item_data aliases for client_data functions, update doc & tests;

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type"
content="text/html; charset=utf-8" /><style
type="text/css"><!--
#msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:'':'';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer { font-family:
verdana,arial,helvetica,sans-serif; font-size: 10pt;  }
#msg dl a { font-weight: bold}
#msg dl a:link    { color:#fc3; }
#msg dl a:active  { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt;
font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding:
6px; }
#msg ul, pre { overflow: auto; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid;
padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family:
verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff  {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch
.binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<title>[766] trunk/wxruby2: Added item_data aliases for client_data
functions, update doc & tests;</title>
</head>
<body>

<div id="msg">
<dl>
<dt>Revision</dt> <dd>766</dd>
<dt>Author</dt> <dd>brokentoy</dd>
<dt>Date</dt> <dd>2006-12-01 12:40:06 -0500 (Fri, 01 Dec
2006)</dd>
</dl>

<h3>Log Message</h3>
<pre>Added item_data aliases for client_data functions, update doc &
tests;
also extend and tidy treectrl item_data tests</pre>

<h3>Modified Paths</h3>
<ul>
<li><a
href="#trunkwxruby2doctextilecontrolwithitemstxtl">trunk/wxruby2/doc/textile/controlwithitems.txtl</a></li>
<li><a
href="#trunkwxruby2teststest_item_datarb">trunk/wxruby2/tests/test_item_data.rb</a></li>
</ul>

<h3>Added Paths</h3>
<ul>
<li><a
href="#trunkwxruby2libwxclasseschoicerb">trunk/wxruby2/lib/wx/classes/choice.rb</a></li>
<li><a
href="#trunkwxruby2libwxclassescomboboxrb">trunk/wxruby2/lib/wx/classes/combobox.rb</a></li>
<li><a
href="#trunkwxruby2libwxclasseslistboxrb">trunk/wxruby2/lib/wx/classes/listbox.rb</a></li>
</ul>

</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkwxruby2doctextilecontrolwithitemstxtl"></a>
<div class="modfile"><h4>Modified:
trunk/wxruby2/doc/textile/controlwithitems.txtl (765 => 766)</h4>
<pre class="diff"><span>
<span class="info">---
trunk/wxruby2/doc/textile/controlwithitems.txtl&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-11-30
01:21:25 UTC (rev 765)
+++
trunk/wxruby2/doc/textile/controlwithitems.txtl&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-12-01
17:40:06 UTC (rev 766)
</span><span class="lines">@@ -1,26 +1,18 @@
</span><span class="cx"> h1(#wxcontrolwithitems).
Wx::ControlWithItems
</span><span class="cx"> 
</span><del>-This class is an abstract base class for some Widgets
controls which contain
-several items, such as "ListBox":listbox.html and 
-"CheckListBox":checklistbox.html derived from it, 
-"Choice":choice.html and "ComboBox":combobox.html.
</del><ins>+This class is an abstract base class for several Widgets
controls which
+contain several items, such as "ListBox":listbox.html and
+"CheckListBox":checklistbox.html derived from it,
"Choice":choice.html
+and "ComboBox":combobox.html.
</ins><span class="cx"> 
</span><span class="cx"> It defines the methods for
accessing the controls items and although each of
</span><span class="cx"> the derived classes implements
them differently, they still all conform to the
</span><span class="cx"> same interface.
</span><span class="cx"> 
</span><span class="cx"> The items in a ControlWithItems
have (non empty) string labels and,
</span><del>-optionally, client data associated with them. Client
data may be of two
-different kinds: either simple untyped (@void *@) pointers which are simply
-stored by the control but not used in any way by it, or typed pointers
-(@ClientData *@) which are owned by the control meaning that the typed
-client data (and only it) will be deleted when an item is 
-"deleted":controlwithitemsdelete.html or the entire control is 
-"cleared":controlwithitemsclear.html (which also happens when it is
-destroyed). Finally note that in the same control all items must have client
-data of the same type (typed or untyped), if any. This type is determined by
-the first call to "Append":controlwithitemsappend.html (the version
with
-client data pointer) or
"set_client_data":#ControlWithItems_setclientdata.
</del><ins>+optionally, item data associated with them. Any ruby
object may be set
+as item data for an item with a control, allowing linking of core ruby
+program objects with GUI code.
</ins><span class="cx"> 
</span><span class="cx"> h2. Derived from
</span><span class="cx"> 
</span><span class="lines">@@ -40,9 +32,8 @@
</span><span class="cx"> *
"ControlWithItems#clear":#ControlWithItems_clear
</span><span class="cx"> *
"ControlWithItems#delete":#ControlWithItems_delete
</span><span class="cx"> *
"ControlWithItems#find_string":#ControlWithItems_findstring
</span><del>-*
"ControlWithItems#get_client_data":#ControlWithItems_getclientdata
-*
"ControlWithItems#get_client_object":#ControlWithItems_getclientobject
</del><span class="cx"> *
"ControlWithItems#get_count":#ControlWithItems_getcount
</span><ins>+*
"ControlWithItems#get_item_data":#ControlWithItems_getitemdata
</ins><span class="cx"> *
"ControlWithItems#get_selection":#ControlWithItems_getselection
</span><span class="cx"> *
"ControlWithItems#get_string":#ControlWithItems_getstring
</span><span class="cx"> *
"ControlWithItems#get_string_selection":#ControlWithItems_getstringselection
</span><span class="lines">@@ -50,8 +41,7 @@
</span><span class="cx"> *
"ControlWithItems#is_empty":#ControlWithItems_isempty
</span><span class="cx"> *
"ControlWithItems#number":#ControlWithItems_number
</span><span class="cx"> *
"ControlWithItems#select":#ControlWithItems_select
</span><del>-*
"ControlWithItems#set_client_data":#ControlWithItems_setclientdata
-*
"ControlWithItems#set_client_object":#ControlWithItems_setclientobject
</del><ins>+*
"ControlWithItems#set_item_data":#ControlWithItems_setitemdata
</ins><span class="cx"> *
"ControlWithItems#set_selection":#ControlWithItems_setselection
</span><span class="cx"> *
"ControlWithItems#set_string":#ControlWithItems_setstring
</span><span class="cx"> *
"ControlWithItems#set_string_selection":#ControlWithItems_setstringselection
</span><span class="lines">@@ -133,51 +123,36 @@
</span><span class="cx"> not found.
</span><span class="cx"> 
</span><span class="cx"> 
</span><del>-h3(#ControlWithItems_getclientdata).
ControlWithItems#get_client_data
</del><ins>+h3(#ControlWithItems_getcount).
ControlWithItems#get_count
</ins><span class="cx"> 
</span><del>-  *get_client_data*(%(arg-type)Integer% n)
</del><ins>+ Integer *get_count*()
</ins><span class="cx"> 
</span><del>-Returns a pointer to the client data associated with
the given item (if any).
-It is an error to call this function for a control which doesn''t have
untyped
-client data at all although it is ok to call it even if the given item
doesn''t
-have any client data associated with it (but other items do).
</del><ins>+Returns the number of items in the control.
</ins><span class="cx"> 
</span><del>-h4. Parameters
</del><ins>+h4. See also
</ins><span class="cx"> 
</span><del>-* _n_ The zero-based position of the item.
</del><ins>+"is_empty":#ControlWithItems_isempty
</ins><span class="cx"> 
</span><del>-h4. Return value
</del><ins>+h3(#ControlWithItems_getitemdata).
ControlWithItems#get_item_data
</ins><span class="cx"> 
</span><del>-A pointer to the client data, or @NULL@ if not present.
</del><ins>+  Object *get_item_data*(%(arg-type)Integer% n)
</ins><span class="cx"> 
</span><ins>+Returns the ruby object previously set as data for the
given item in the
+control. If no object has been set as data, then @nil@ is returned.
</ins><span class="cx"> 
</span><del>-h3(#ControlWithItems_getclientobject).
ControlWithItems#get_client_object
</del><ins>+Note that in WxWidgets C++, this method is called
GetClientData;
+therefore *get_client_data* is an alias in WxRuby for this method. THe
+name *get_item_data* is preferred for clarity and consistency with the
+other classes such as "TreeCtrl":treectrl.html and
+"ListCtrl":listctrl.html which offer a similar feature.
</ins><span class="cx"> 
</span><del>- "ClientData":clientdata.html
*get_client_object*(%(arg-type)Integer% n)
-
-Returns a pointer to the client data associated with the given item (if any).
-It is an error to call this function for a control which doesn''t have
typed
-client data at all although it is ok to call it even if the given item
doesn''t
-have any client data associated with it (but other items do).
-
</del><span class="cx"> h4. Parameters
</span><span class="cx"> 
</span><span class="cx"> * _n_ The zero-based position of
the item.
</span><span class="cx"> 
</span><del>-h4. Return value
-
-A pointer to the client data, or @NULL@ if not present.
-
-
-h3(#ControlWithItems_getcount). ControlWithItems#get_count
-
- Integer *get_count*()
-
-Returns the number of items in the control.
-
</del><span class="cx"> h4. See also
</span><span class="cx"> 
</span><del>-"is_empty":#ControlWithItems_isempty
</del><ins>+"set_item_data":#ControlWithItems_setitemdata
</ins><span class="cx"> 
</span><span class="cx"> 
</span><span class="cx">
h3(#ControlWithItems_getselection). ControlWithItems#get_selection
</span><span class="lines">@@ -253,10 +228,9 @@
</span><span class="cx"> 
</span><span class="cx"> h4. Return value
</span><span class="cx"> 
</span><del>-The return value is the index of the newly inserted
item. If the insertion failed
-for some reason, -1 is returned.
</del><ins>+The return value is the index of the newly inserted
item. If the
+insertion failed for some reason, -1 is returned.
</ins><span class="cx"> 
</span><del>-
</del><span class="cx"> h3(#ControlWithItems_isempty).
ControlWithItems#is_empty
</span><span class="cx"> 
</span><span class="cx">  Boolean *is_empty*()
</span><span class="lines">@@ -267,18 +241,6 @@
</span><span class="cx"> 
</span><span class="cx">
"get_count":#ControlWithItems_getcount
</span><span class="cx"> 
</span><del>-
-h3(#ControlWithItems_number). ControlWithItems#number
-
- Integer *number*()
-
-*Obsolescence note:* This method is obsolete and was replaced with
-"get_count":#ControlWithItems_getcount, please use the new method in
-the new code. This method is only available if Widgets was compiled with 
-@WXWIN_COMPATIBILITY_2_2@ defined and will disappear completely in
-future versions.
-
-
</del><span class="cx"> h3(#ControlWithItems_select).
ControlWithItems#select
</span><span class="cx"> 
</span><span class="cx">   *select*(%(arg-type)Integer% n)
</span><span class="lines">@@ -288,44 +250,36 @@
</span><span class="cx"> multiple selection.
</span><span class="cx"> 
</span><span class="cx"> 
</span><del>-h3(#ControlWithItems_setclientdata).
ControlWithItems#set_client_data
</del><ins>+h3(#ControlWithItems_setitemdata).
ControlWithItems#set_item_data
</ins><span class="cx"> 
</span><del>-  *set_client_data*(%(arg-type)Integer% n, 
%(arg-type)% data)
</del><ins>+  *set_item_data*(%(arg-type)Integer% n, 
%(arg-type)Object% data)
</ins><span class="cx"> 
</span><del>-Associates the given untyped client data pointer with
the given item. Note that
-it is an error to call this function if any typed client data pointers had been
-associated with the control items before.
</del><ins>+Associates the ruby object with the given item in the
control. This
+useful feature enables the linking of program data (for example, objects
+representing a database record) with the GUI, so that on subsequent
+interaction with the control, GUI code can use
+"get_item_data":#ControlWithItems_getitemdata to determine which
program
+data object is being interacted with. Any ruby object may be set as item
+data, though it may be unwise to use volatile objects such as sockets or
+files as item data.
</ins><span class="cx"> 
</span><del>-h4. Parameters
</del><ins>+Note that in WxWidgets C++, this method is called
SetClientData;
+therefore *set_client_data* is an alias in WxRuby for this method. THe
+name *set_item_data* is preferred for clarity and consistency with the
+other classes such as "TreeCtrl":treectrl.html and
+"ListCtrl":listctrl.html which offer a similar feature.
</ins><span class="cx"> 
</span><del>-* _n_ The zero-based item index.
-* _data_ The client data to associate with the item.
-
-
-h3(#ControlWithItems_setclientobject). ControlWithItems#set_client_object
-
-  *set_client_object*(%(arg-type)Integer% n,  %(arg-type)ClientData% data)
-
-Associates the given typed client data pointer with the given item: the 
-_data_ object will be deleted when the item is deleted (either explicitly
-by using "Deletes":controlwithitemsdelete.html or implicitly when the
-control itself is destroyed).
-
-Note that it is an error to call this function if any untyped client data
-pointers had been associated with the control items before.
-
</del><span class="cx"> h4. Parameters
</span><span class="cx"> 
</span><span class="cx"> * _n_ The zero-based item index.
</span><span class="cx"> * _data_ The client data to
associate with the item.
</span><span class="cx"> 
</span><del>-
</del><span class="cx">
h3(#ControlWithItems_setselection). ControlWithItems#set_selection
</span><span class="cx"> 
</span><span class="cx">  
*set_selection*(%(arg-type)Integer% n)
</span><span class="cx"> 
</span><span class="cx"> Sets the selection to the given
item n or removes the selection entirely
</span><del>-if n $==$ @NOT_FOUND@.
</del><ins>+if n == -1.
</ins><span class="cx"> 
</span><span class="cx"> Note that this does not cause any
command events to be emitted nor does it
</span><span class="cx"> deselect any other items in the
controls which support multiple selections.
</span><span class="lines">@@ -364,8 +318,8 @@
</span><span class="cx"> 
</span><span class="cx"> h4. Return value
</span><span class="cx"> 
</span><del>- if the specified string has been selected,  if it
wasn''t found in
-the control.
</del><ins>+@true@ if the specified string has been selected,
@false@ if it wasn''t
+found in the control.
</ins><span class="cx"> 
</span><span class="cx"> h4. See also
</span><span class="cx"> 
</span></span></pre></div>
<a id="trunkwxruby2libwxclasseschoicerb"></a>
<div class="addfile"><h4>Added:
trunk/wxruby2/lib/wx/classes/choice.rb (0 => 766)</h4>
<pre class="diff"><span>
<span class="info">---
trunk/wxruby2/lib/wx/classes/choice.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
(rev 0)
+++
trunk/wxruby2/lib/wx/classes/choice.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-12-01
17:40:06 UTC (rev 766)
</span><span class="lines">@@ -0,0 +1,4 @@
</span><ins>+class Wx::Choice
+  alias :get_item_data :get_client_data
+  alias :set_item_data :set_client_data
+end
</ins></span></pre></div>
<a id="trunkwxruby2libwxclassescomboboxrb"></a>
<div class="addfile"><h4>Added:
trunk/wxruby2/lib/wx/classes/combobox.rb (0 => 766)</h4>
<pre class="diff"><span>
<span class="info">---
trunk/wxruby2/lib/wx/classes/combobox.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
(rev 0)
+++
trunk/wxruby2/lib/wx/classes/combobox.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-12-01
17:40:06 UTC (rev 766)
</span><span class="lines">@@ -0,0 +1,4 @@
</span><ins>+class Wx::ComboBox
+  alias :get_item_data :get_client_data
+  alias :set_item_data :set_client_data
+end
</ins></span></pre></div>
<a id="trunkwxruby2libwxclasseslistboxrb"></a>
<div class="addfile"><h4>Added:
trunk/wxruby2/lib/wx/classes/listbox.rb (0 => 766)</h4>
<pre class="diff"><span>
<span class="info">---
trunk/wxruby2/lib/wx/classes/listbox.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
(rev 0)
+++
trunk/wxruby2/lib/wx/classes/listbox.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-12-01
17:40:06 UTC (rev 766)
</span><span class="lines">@@ -0,0 +1,4 @@
</span><ins>+class Wx::ListBox
+  alias :get_item_data :get_client_data
+  alias :set_item_data :set_client_data
+end
</ins></span></pre></div>
<a id="trunkwxruby2teststest_item_datarb"></a>
<div class="modfile"><h4>Modified:
trunk/wxruby2/tests/test_item_data.rb (765 => 766)</h4>
<pre class="diff"><span>
<span class="info">---
trunk/wxruby2/tests/test_item_data.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-11-30
01:21:25 UTC (rev 765)
+++
trunk/wxruby2/tests/test_item_data.rb&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp2006-12-01
17:40:06 UTC (rev 766)
</span><span class="lines">@@ -20,10 +20,10 @@
</span><span class="cx"> class TestItemData <
Test::Unit::TestCase
</span><span class="cx">   def
assert_retrievable_data(ctrl, n, test_value)
</span><span class="cx">     compare = Marshal.load(
Marshal.dump(test_value) )
</span><del>-    ctrl.set_client_data(n, test_value)
-    assert_equal(compare, ctrl.get_client_data(n) )
</del><ins>+    ctrl.set_item_data(n, test_value)
+    assert_equal(compare, ctrl.get_item_data(n) )
</ins><span class="cx">     GC.start
</span><del>-    assert_equal(compare, ctrl.get_client_data(n) )
</del><ins>+    assert_equal(compare, ctrl.get_item_data(n) )
</ins><span class="cx">   end
</span><span class="cx"> 
</span><span class="cx">   def
do_control_with_items_assertions(f)
</span><span class="lines">@@ -34,21 +34,26 @@
</span><span class="cx"> 
</span><span class="cx">   def test_treectrl_itemdata
</span><span class="cx">     f =
CtrlContainerFrame.new(Wx::TreeCtrl)
</span><del>-    root = f.control.add_root(''foo'')
</del><ins>+    tree = f.control
+    root = tree.add_root(''foo'')
+    assert_nil(tree.get_item_data( tree.get_root_item))
</ins><span class="cx"> 
</span><del>-    id = f.control.append_item(root, ''a
hash'', -1, -1, { :a => 7 })
-    assert_equal({:a => 7 }, 
-                  f.control.get_item_data(id) )
</del><ins>+    id = tree.append_item(root, ''a
hash'', -1, -1, { :a => 7 })
+    assert_equal({:a => 7 }, tree.get_item_data(id) )
</ins><span class="cx"> 
</span><del>-    id = f.control.prepend_item(root, ''a
float'', -1, -1, 7.8)
-    assert_equal(7.8, 
</del><ins>+    id = tree.prepend_item(root, ''a
float'', -1, -1, 7.8)
+    assert_equal(7.8, tree.get_item_data(id) )
+    GC.start
+    assert_equal(7.8, tree.get_item_data(id) )
+
+    id = tree.prepend_item(root, ''an array'', -1, -1)
+    assert_nil( tree.get_item_data(id) )
+    tree.set_item_data(id, %w|foo bar baz|)
+    assert_equal(%w|foo bar baz|,
</ins><span class="cx">                 
f.control.get_item_data(id) )
</span><del>-
-    id = f.control.prepend_item(root, ''an array'', -1, -1,
%w|foo bar baz|)
</del><span class="cx">     GC.start
</span><span class="cx">     assert_equal(%w|foo bar baz|,
</span><span class="cx">                 
f.control.get_item_data(id) )
</span><del>-
</del><span class="cx">     f.close(true)
</span><span class="cx">   end
</span><span class="cx"> 
</span></span></pre>
</div>
</div>

</body>
</html>
Apparently Analagous Threads

Search for more reasonably related threads
wxruby development - Dec 2006 - [766] trunk/wxruby2: Added item_data aliases for client_data functions, update doc & tests;

[Wxruby-development] [766] trunk/wxruby2: Added item_data aliases for client_data functions, update doc & tests;

Apparently Analagous Threads

Wisdom of the Ancients
