📄 gtk_tut-11.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML><HEAD> <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9"> <TITLE>GTK v1.2 Tutorial: CList Widget</TITLE> <LINK HREF="gtk_tut-12.html" REL=next> <LINK HREF="gtk_tut-10.html" REL=previous> <LINK HREF="gtk_tut.html#toc11" REL=contents></HEAD><BODY BGCOLOR="#FFFFFF"><A HREF="gtk_tut-12.html">Next</A><A HREF="gtk_tut-10.html">Previous</A><A HREF="gtk_tut.html#toc11">Contents</A><HR NOSHADE><H2><A NAME="s11">11. CList Widget</A></H2><P>The GtkCList widget has replaced the GtkList widget (which is stillavailable).<P>The GtkCList widget is a multi-column list widget that is capable ofhandling literally thousands of rows of information. Each column canoptionally have a title, which itself is optionally active, allowingus to bind a function to its selection.<P><H2><A NAME="ss11.1">11.1 Creating a GtkCList widget</A></H2><P>Creating a GtkCList is quite straightforward, once you have learnedabout widgets in general. It provides the almost standard two ways,that is the hard way, and the easy way. But before we create it, thereis one thing we should figure out beforehand: how many columns shouldit have?<P>Not all columns have to be visible and can be used to store data thatis related to a certain cell in the list.<P><BLOCKQUOTE><CODE><PRE>GtkWidget *gtk_clist_new ( gint columns );GtkWidget *gtk_clist_new_with_titles( gint columns, gchar *titles[] );</PRE></CODE></BLOCKQUOTE><P>The first form is very straight forward, the second might require someexplanation. Each column can have a title associated with it, and thistitle can be a label or a button that reacts when we click on it. Ifwe use the second form, we must provide pointers to the title texts,and the number of pointers should equal the number of columnsspecified. Of course we can always use the first form, and manuallyadd titles later.<P>Note: the GtkCList widget does not have its own scrollbars and shouldbe placed within a GtkScrolledWindow widget if your require thisfunctionality. This is a change from the GTK 1.0 implementation.<P><H2><A NAME="ss11.2">11.2 Modes of operation</A></H2><P>There are several attributes that can be used to alter the behaviour ofa GtkCList. First there is<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_selection_mode( GtkCList *clist, GtkSelectionMode mode );</PRE></CODE></BLOCKQUOTE><P>which, as the name implies, sets the selection mode of theGtkCList. The first argument is the GtkCList widget, and the secondspecifies the cell selection mode (they are defined in gtkenums.h). Atthe time of this writing, the following modes are available to us:<P><UL><LI> GTK_SELECTION_SINGLE - The selection is either NULL or containsa GList pointer for a single selected item.</LI><LI> GTK_SELECTION_BROWSE - The selection is NULL if the listcontains no widgets or insensitive ones only, otherwise it contains aGList pointer for one GList structure, and therefore exactly one listitem.</LI><LI> GTK_SELECTION_MULTIPLE - The selection is NULL if no list itemsare selected or a GList pointer for the first selected item. That inturn points to a GList structure for the second selected item and soon. This is currently the <B>default</B> for the GtkCList widget.</LI><LI> GTK_SELECTION_EXTENDED - The selection is always NULL.</LI></UL><P>Others might be added in later revisions of GTK.<P>We can also define what the border of the GtkCList widget should looklike. It is done through<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_shadow_type( GtkCList *clist, GtkShadowType border );</PRE></CODE></BLOCKQUOTE><P>And the possible values for the second argument are<P><UL><LI> GTK_SHADOW_NONE</LI><LI> GTK_SHADOW_IN</LI><LI> GTK_SHADOW_OUT</LI><LI> GTK_SHADOW_ETCHED_IN</LI><LI> GTK_SHADOW_ETCHED_OUT</LI></UL><P><H2><A NAME="ss11.3">11.3 Working with titles</A></H2><P>When you create a GtkCList widget, you will also get a set of titlebuttons automatically. They live in the top of the CList window, andcan act either as normal buttons that respond to being pressed, orthey can be passive, in which case they are nothing more than atitle. There are four different calls that aid us in setting thestatus of the title buttons.<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_column_title_active( GtkCList *clist, gint column );void gtk_clist_column_title_passive( GtkCList *clist, gint column );void gtk_clist_column_titles_active( GtkCList *clist );void gtk_clist_column_titles_passive( GtkCList *clist );</PRE></CODE></BLOCKQUOTE><P>An active title is one which acts as a normal button, a passive one isjust a label. The first two calls above will activate/deactivate thetitle button above the specific column, while the last two callsactivate/deactivate all title buttons in the supplied clist widget.<P>But of course there are those cases when we don't want them at all,and so they can be hidden and shown at will using the following twocalls.<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_column_titles_show( GtkCList *clist );void gtk_clist_column_titles_hide( GtkCList *clist );</PRE></CODE></BLOCKQUOTE><P>For titles to be really useful we need a mechanism to set and changethem, and this is done using<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_column_title( GtkCList *clist, gint column, gchar *title );</PRE></CODE></BLOCKQUOTE><P>Note that only the title of one column can be set at a time, so if allthe titles are known from the beginning, then I really suggest usinggtk_clist_new_with_titles (as described above) to set them. Saves youcoding time, and makes your program smaller. There are some caseswhere getting the job done the manual way is better, and that's whennot all titles will be text. GtkCList provides us with title buttonsthat can in fact incorporate whole widgets, for example a pixmap. It'sall done through<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_column_widget( GtkCList *clist, gint column, GtkWidget *widget );</PRE></CODE></BLOCKQUOTE><P>which should require no special explanation.<P><H2><A NAME="ss11.4">11.4 Manipulating the list itself</A></H2><P>It is possible to change the justification for a column, and it isdone through<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_column_justification( GtkCList *clist, gint column, GtkJustification justification );</PRE></CODE></BLOCKQUOTE><P>The GtkJustification type can take the following values:<P><UL><LI>GTK_JUSTIFY_LEFT - The text in the column will begin from theleft edge.</LI><LI>GTK_JUSTIFY_RIGHT - The text in the column will begin from theright edge.</LI><LI>GTK_JUSTIFY_CENTER - The text is placed in the center of thecolumn.</LI><LI>GTK_JUSTIFY_FILL - The text will use up all available space inthe column. It is normally done by inserting extra blank spacesbetween words (or between individual letters if it's a singleword). Much in the same way as any ordinary WYSIWYG text editor.</LI></UL><P>The next function is a very important one, and should be standard inthe setup of all GtkCList widgets. When the list is created, the widthof the various columns are chosen to match their titles, and sincethis is seldom the right width we have to set it using<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_column_width( GtkCList *clist, gint column, gint width );</PRE></CODE></BLOCKQUOTE><P>Note that the width is given in pixels and not letters. The same goesfor the height of the cells in the columns, but as the default valueis the height of the current font this isn't as critical to theapplication. Still, it is done through<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_row_height( GtkCList *clist, gint height );</PRE></CODE></BLOCKQUOTE><P>Again, note that the height is given in pixels.<P>We can also move the list around without user interaction, however, itdoes require that we know what we are looking for. Or in other words,we need the row and column of the item we want to scroll to.<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_moveto( GtkCList *clist, gint row, gint column, gfloat row_align, gfloat col_align );</PRE></CODE></BLOCKQUOTE><P>The gfloat row_align is pretty important to understand. It's a valuebetween 0.0 and 1.0, where 0.0 means that we should scroll the list sothe row appears at the top, while if the value of row_align is 1.0,the row will appear at the bottom instead. All other values between0.0 and 1.0 are also valid and will place the row between the top andthe bottom. The last argument, gfloat col_align works in the same way,though 0.0 marks left and 1.0 marks right instead.<P>Depending on the application's needs, we don't have to scroll to anitem that is already visible to us. So how do we know if it isvisible? As usual, there is a function to find that out as well.<P><BLOCKQUOTE><CODE><PRE>GtkVisibility gtk_clist_row_is_visible( GtkCList *clist, gint row );</PRE></CODE></BLOCKQUOTE><P>The return value is is one of the following:<P><UL><LI>GTK_VISIBILITY_NONE</LI><LI>GTK_VISIBILITY_PARTIAL</LI><LI>GTK_VISIBILITY_FULL</LI></UL><P>Note that it will only tell us if a row is visible. Currently there isno way to determine this for a column. We can get partial informationthough, because if the return is GTK_VISIBILITY_PARTIAL, then some ofit is hidden, but we don't know if it is the row that is being cut bythe lower edge of the listbox, or if the row has columns that areoutside.<P>We can also change both the foreground and background colors of aparticular row. This is useful for marking the row selected by theuser, and the two functions that is used to do it are<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_foreground( GtkCList *clist, gint row, GdkColor *color );void gtk_clist_set_background( GtkCList *clist, gint row, GdkColor *color );</PRE></CODE></BLOCKQUOTE><P>Please note that the colors must have been previously allocated.<P><H2><A NAME="ss11.5">11.5 Adding rows to the list</A></H2><P>We can add rows in three ways. They can be prepended or appended tothe list using<P><BLOCKQUOTE><CODE><PRE>gint gtk_clist_prepend( GtkCList *clist, gchar *text[] );gint gtk_clist_append( GtkCList *clist, gchar *text[] );</PRE></CODE></BLOCKQUOTE><P>The return value of these two functions indicate the index of the rowthat was just added. We can insert a row at a given place using<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_insert( GtkCList *clist, gint row, gchar *text[] );</PRE></CODE></BLOCKQUOTE><P>In these calls we have to provide a collection of pointers that arethe texts we want to put in the columns. The number of pointers shouldequal the number of columns in the list. If the text[] argument isNULL, then there will be no text in the columns of the row. This isuseful, for example, if we want to add pixmaps instead (something thathas to be done manually).<P>Also, please note that the numbering of both rows and columns start at 0.<P>To remove an individual row we use<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_remove( GtkCList *clist, gint row );</PRE></CODE></BLOCKQUOTE><P>There is also a call that removes all rows in the list. This is a lotfaster than calling gtk_clist_remove once for each row, which is theonly alternative.<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_clear( GtkCList *clist );</PRE></CODE></BLOCKQUOTE><P>There are also two convenience functions that should be used when alot of changes have to be made to the list. This is to prevent thelist flickering while being repeatedly updated, which may be highlyannoying to the user. So instead it is a good idea to freeze the list,do the updates to it, and finally thaw it which causes the list to beupdated on the screen.<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_freeze( GtkCList * clist );void gtk_clist_thaw( GtkCList * clist );</PRE></CODE></BLOCKQUOTE><P><H2><A NAME="ss11.6">11.6 Setting text and pixmaps in the cells</A></H2><P>A cell can contain a pixmap, text or both. To set them the followingfunctions are used.<P><BLOCKQUOTE><CODE><PRE>void gtk_clist_set_text( GtkCList *clist, gint row, gint column, gchar *text );void gtk_clist_set_pixmap( GtkCList *clist, gint row, gint column, GdkPixmap *pixmap, GdkBitmap *mask );⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -