diff --git a/doc/ChangeLog b/doc/ChangeLog index 6af7538ad..ada1d9343 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2004-08-18 Shane Landrum + + * en/Gtk/ListStore.xml: Added docs. + 2004-08-13 Shane Landrum * DragBeginArgs.xml diff --git a/doc/en/Gtk/ListStore.xml b/doc/en/Gtk/ListStore.xml index a300e53cd..12aa346e3 100644 --- a/doc/en/Gtk/ListStore.xml +++ b/doc/en/Gtk/ListStore.xml @@ -12,7 +12,7 @@ The ListStore is a columned list data structure to be used with widget. It is the model part in Model/View/Controller design paradigm. The contents of the ListStore can be sorted and are drag-and-drop ready. - To be added + GLib.Object @@ -71,6 +71,8 @@ To be added + + Method @@ -79,8 +81,8 @@ - To be added - To be added + Emits a event. + @@ -94,10 +96,10 @@ - To be added - To be added: an object of type 'int' - To be added: an object of type 'Gtk.SortType' - To be added + Sets the column number to sort by. + A , the column number to sort by. + A + @@ -113,12 +115,13 @@ - To be added - To be added: an object of type 'int' - To be added: an object of type 'Gtk.TreeIterCompareFunc' - To be added: an object of type 'IntPtr' - To be added: an object of type 'Gtk.DestroyNotify' - To be added + Sets a sort function to be used for the column + . + A for the column number. + A + A + A , function that will be run on destruction of + @@ -133,11 +136,11 @@ - To be added - To be added: an object of type 'Gtk.TreeIterCompareFunc' - To be added: an object of type 'IntPtr' - To be added: an object of type 'Gtk.DestroyNotify' - To be added + Set the function that will be used by default to sort columns. + A + A (FIXME: explain this) + A , function that will be run on destruction of + @@ -151,11 +154,12 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'Gtk.SelectionData' - To be added: an object of type 'bool' - To be added + Returns true if the row at can + have dropped on it. + A + A + A boolean. + @@ -169,11 +173,11 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'Gtk.SelectionData' - To be added: an object of type 'bool' - To be added + Drags data received into this object. + A , the destination path of the drag + A , the data that was dragged + A boolean, true if the data was successfully received. + @@ -187,11 +191,13 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'Gtk.SelectionData' - To be added: an object of type 'bool' - To be added + Method used when this ListStore is part of a source widget + for a drag-and-drop operation; gets the data that was dragged from the + associated widget. + a + A + A , true if the operation succeeded. + @@ -204,10 +210,10 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'bool' - To be added + Returns whether or not a given row can be dragged. + a + A boolean, true if the row is draggable. + @@ -220,10 +226,10 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'bool' - To be added + When this ListStore is the data source for a drag operation and the drag operation is a move, this method runs to delete the data after the data has been received by the target widget. + A , the path of the data to delete. + A , true if the operation succeeds. + @@ -237,10 +243,10 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'Gtk.TreeIter' - To be added + Fires a event. Call this after changing a row so that the view widget for this ListStore will update. + a + a + @@ -253,9 +259,9 @@ - To be added - To be added: an object of type 'Gtk.TreeModelForeachFunc' - To be added + Runs a method on every row of a ListStore. + A to run over every row. + @@ -268,10 +274,10 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'bool' - To be added + Initializes with the first iterator in the ListStore (the top item). + A to reset + A , true if the operation is successful, false if the ListStore is empty. + @@ -285,10 +291,12 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'Gtk.TreeIter' - To be added + Emits a event. This is meant to be called whenever the child state of a node changes. + a to pass to the event + a to pass to the event + This is mandated by the , but it + shouldn't get used much for ListStores because they don't generally + have child nodes. @@ -301,10 +309,10 @@ - To be added - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'Gtk.TreePath' - To be added + Turns a specified by into a . + a + a + @@ -317,10 +325,10 @@ - To be added - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'bool' - To be added + Tests whether a given row has a child node. + a + A , always false for ListStores. + This is mandated by @@ -333,9 +341,12 @@ - To be added - To be added: an object of type 'Gtk.TreeIter' - To be added + Lets the ListStore reference the row pointed to by . + a + + This function is primarily meant as a way for views to let caching model know when nodes are being displayed (and hence, whether or not to cache that node.) For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. + A model should be expected to be able to get an iter independent of its reffed state. + @@ -348,10 +359,10 @@ - To be added - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'int' - To be added + Returns the number of children that has. If is null, as in the case of all ListStore objects, this will return the number of top-level items. + a + a + FIXME: Why does ListStore.custom call gtk_tree_model_iter_n_children? @@ -365,10 +376,10 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'Gtk.TreeIter' - To be added + Fires a event. + a to pass to the event. + a see cref="T:Gtk.TreeIter" /> to pass to the event. + @@ -381,9 +392,9 @@ - To be added - To be added: an object of type 'Gtk.TreePath' - To be added + Fires a event. + a to pass to the event. + @@ -413,9 +424,16 @@ - To be added - To be added: an object of type 'Gtk.TreeIter' - To be added + Lets the ListStore unref the row at . + a + + This is an optional method + for models to implement. To be more specific, models may ignore + this call as it exists primarily for performance reasons. + For more information on what this means, see + . Please note that + nodes that are deleted are not unreffed. + @@ -427,7 +445,7 @@ Removes all data from the store. - To be added + @@ -459,10 +477,10 @@ - Sets the value of the specified column in the row pointed by iter. - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'int' - To be added: an object of type 'GLib.Value' + Sets the value of the specified column in the row pointed by . + a + a , the column number + a The type of specified column must be a . @@ -501,9 +519,9 @@ System.Int32 - To be added - To be added: an object of type 'int' - To be added + The number of columns in this ListStore. + A + @@ -513,9 +531,10 @@ Gtk.TreeModelFlags - To be added - To be added: an object of type 'Gtk.TreeModelFlags' - To be added + The flags for this ListStore. + A + Flags are about the shape of this object's data; see the + class documentation for more details. @@ -526,8 +545,8 @@ - To be added - To be added + Fired when a column has changed. + @@ -538,8 +557,8 @@ - To be added - To be added + Fired when the display of a given row's children is toggled. + @@ -550,8 +569,8 @@ - To be added - To be added + Fired when a row of data is inserted. + @@ -562,8 +581,8 @@ - To be added - To be added + Fired when a row is deleted. + @@ -574,8 +593,8 @@ - To be added - To be added + Fired when a row has changed. + @@ -586,8 +605,8 @@ - To be added - To be added + Fired when the order of rows has changed. + @@ -601,11 +620,12 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'int' - To be added: an object of type 'bool' - To be added + Sets to be the child of this ListStore, using the given index. The first index is 0. If is too big, or this ListStore has no rows, is set to an invalid iterator and false is returned. For ListStore objects, the th root node is set, since they don't have a tree-like structure. + + a + a + a , true if has an th child. + This is a custom binding for Gtk# which assumes that the current object is the parent. An alternate invocation form that parallels the C API is available. @@ -620,12 +640,13 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'int' - To be added: an object of type 'bool' - To be added + + Sets to be the child of , using the given index. The first index is 0. If is too big, or has no children, is set to an invalid iterator and false is returned. will remain a valid node after this function has been called. As a special case, if is , then the th root node is set. + + a + a + a , true if has an th child. + This invocation form is closer to the underlying C API, but it's probably less useful for most C# purposes. @@ -639,11 +660,11 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'string' - To be added: an object of type 'bool' - To be added + Marshals a path string into a object that points to a row in this tree. + a to be set by this method + A path string + A , true if this string is a valid path for this ListStore. + @@ -657,11 +678,11 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'bool' - To be added + + , an object that will be set to point to the first child. + a , the parent row. + A , true if has children. + In general, this will return false, as ListStore isn't tree-shaped. However, if is , will return the list itself, since they're all children of the root. @@ -675,11 +696,11 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'Gtk.TreePath' - To be added: an object of type 'bool' - To be added + Gets an iterator object for the given . + a to set to point to the row. + a + A , true if the row exists + @@ -693,11 +714,11 @@ - To be added - To be added: an object of type 'Gtk.TreeIter&' - To be added: an object of type 'Gtk.TreeIter' - To be added: an object of type 'bool' - To be added + Gets the parent row of . + a to set to point to the row. + a , the child row whose parent we want to get + A , true if the parent exists. Since ListStore objects aren't tree-shaped, this will always return false. + @@ -710,10 +731,10 @@ - To be added - a - a - To be added + Appends a new row to the ListStore and puts the objects in in it. + a list , one item for each column of a row. + a pointing to the new row + @@ -726,10 +747,10 @@ - To be added - a - a - To be added + Appends a new row to the ListStore and puts the contents of in it. + a with as many elements as the ListStore has columns. + a pointing to the new row + @@ -742,10 +763,10 @@ - To be added + Marshals the given into a string. a a - To be added + (FIXME: explain the return results.) @@ -759,10 +780,15 @@ - To be added + Move the row pointed to by to the + position after . If + is , + will be moved to point to the start + of the list. + a a - To be added + This only works in unsorted stores. @@ -793,10 +819,15 @@ - To be added + Move the row pointed to by to the + position before . If + is , + will be moved to point to the end + of the list. + a a - To be added + This only works in unsorted stores. @@ -809,10 +840,11 @@ - To be added + Test whether is valid for this ListStore. a - a - To be added + a , true if is valid. + WARNING: this method is slow and is only intended for + debugging/testing purposes. @@ -847,11 +879,11 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - a - a - To be added + Report on which column is currently being used to sort this ListStore. + a , gets filled with the column number that's currently used for sorting + a , the current type of sort (ascending or descending) + a , false if the default sort column for this ListStore is being used, true if some other sort column is being used. + @@ -998,11 +1030,12 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - a + Gets the data from row of column + . + a , the row to look in + a , the column number to look in a - To be added + @@ -1013,9 +1046,10 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - To be added + Find out whether this ListStore has a default sort function. + a , true if there is a default + sort function. + To set a default sort function, use . @@ -1041,9 +1075,14 @@ The above example creates a new three columns list store. The types of the colum - To be added + Sets what types go in each column of a ListStore. a - To be added + This function is meant primarily for #GObjects that inherit + from and should only be used when + constructing a new . It will not + function after a row has been added or after a method on the + interface has been called. + @@ -1056,10 +1095,10 @@ The above example creates a new three columns list store. The types of the colum - To be added - a + Gets the type of data stored in column number . + a , the column to check a - To be added + @@ -1181,10 +1220,10 @@ The above example creates a new three columns list store. The types of the colum - To be added + Default constructor. a a - To be added + @@ -1195,9 +1234,9 @@ The above example creates a new three columns list store. The types of the colum - To be added + Reorders the ListStore. a - To be added + (FIXME: Does this binding work?) @@ -1210,10 +1249,14 @@ The above example creates a new three columns list store. The types of the colum - To be added + Inserts a new row at position . a - a - To be added + a pointing to the new row. + If is larger than the number + of rows on the list, then the new row will be appended to the list. + The row will be empty before this function is called. To set the + value of the new row, use . + @@ -1224,9 +1267,13 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - To be added + Adds a new row to the beginning of the list. + a pointing to the new row. + + + The row will be empty before this function is called. To set the + value of the new row, use . + @@ -1239,10 +1286,17 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - a - To be added + + Inserts a new row before . If + is null, then the row will be appended + to the end of the list. + + a , the row to insert before + a that points to the new row + + The row will be empty before this function is called. To set the + value of the new row, use . + @@ -1255,10 +1309,17 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - a - To be added + + Inserts a new row after . If + is null, then the row will be appended + to the end of the list. + + a , the row to insert before + a that points to the new row + + The row will be empty before this function is called. To set the + value of the new row, use . + @@ -1269,9 +1330,12 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - To be added + Appends a new row to the ListStore. + a that points to the new row. + + The row will be empty before this function is called. To set the + value of the new row, use . + @@ -1285,11 +1349,11 @@ The above example creates a new three columns list store. The types of the colum - To be added - a - a + Fires a event. + a , pointer to the row whose children have been reordered + a , pointer to the row whose children have been reordered a - To be added + This is part of the implementation of . It should be called by other class methods that reorder rows so that the proper events are fired. (FIXME: since lists don't have parents/children, how does this get used in practice? There should be an example here.) @@ -1305,7 +1369,7 @@ The above example creates a new three columns list store. The types of the colum Removes a row from the store. a a - After being removed, iter is set to be the next valid row, or invalidated if it pointed to the last row in the store. + After being removed, is set to be the next valid row, or invalidated if it pointed to the last row in the store. @@ -1320,11 +1384,13 @@ The above example creates a new three columns list store. The types of the colum - To be added + Gets the value of row of column + and puts it in . + a a a - To be added + @@ -1337,11 +1403,11 @@ The above example creates a new three columns list store. The types of the colum - To be added + Advances to the next row. a - a - To be added + a for whether the operation succeeded. + - \ No newline at end of file +