Menu
▾
▴
[Gtk2hs-commit] gtk2hs/gtk/Graphics/UI/Gtk/Display AccelLabel.chs,1.2,1.3 Image.chs.pp,1.3,1.4 Label.chs,1.2,1.3 ProgressBar.chs,1.2,1.3 Statusbar.chs,1.2,1.3
|
From: Duncan C. <dun...@us...> - 2005-02-25 01:12:29
|
Update of /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv24163/gtk/Graphics/UI/Gtk/Display Modified Files: AccelLabel.chs Image.chs.pp Label.chs ProgressBar.chs Statusbar.chs Log Message: Add more module level documentation and tidy up exiting documentation. Also add/modify section headers. Also LGPL'ify remaining modules with permission from Matthew Walton. Index: Image.chs.pp =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/Image.chs.pp,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- Image.chs.pp 15 Feb 2005 17:54:57 -0000 1.3 +++ Image.chs.pp 25 Feb 2005 01:11:32 -0000 1.4 @@ -19,41 +19,94 @@ -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- Lesser General Public License for more details. -- +-- TODO +-- +-- Figure out what other functions are useful within Haskell. Maybe we should +-- support loading Pixmaps without exposing them. +-- +-- Because Haskell is not the best language to modify large images directly +-- only functions are bound that allow loading images from disc or by stock +-- names. +-- +-- Another function for extracting the 'Pixbuf' is added for +-- 'CellRenderer'. +-- -- | -- Maintainer : gtk...@li... -- Stability : provisional -- Portability : portable (depends on GHC) -- --- This widget displays an image. +-- A widget displaying an image -- +module Graphics.UI.Gtk.Display.Image ( +-- * Description +-- +-- | The 'Image' widget displays an image. Various kinds of object can be +-- displayed as an image; most typically, you would load a 'Pixbuf' (\"pixel +-- buffer\") from a file, and then display that. There's a convenience function +-- to do this, 'imageNewFromFile', used as follows: If the file isn't loaded +-- successfully, the image will contain a \"broken image\" icon similar to that +-- used in many web browsers. If you want to handle errors in loading the file +-- yourself, for example by displaying an error message, then load the image +-- with 'pixbufNewFromFile', then create the 'Image' with 'imageNewFromPixbuf'. -- --- * Because Haskell is not the best language to modify large images directly --- only functions are bound that allow loading images from disc or by stock --- names. +-- > image <- imageNewFromFile "myfile.png" -- --- * Another function for extracting the 'Pixbuf' is added for --- 'CellRenderer'. +-- The image file may contain an animation, if so the 'Image' will display +-- an animation ('PixbufAnimation') instead of a static image. -- --- TODO +-- 'Image' is a subclass of 'Misc', which implies that you can align it +-- (center, left, right) and add padding to it, using 'Misc' methods. -- --- * Figure out what other functions are useful within Haskell. Maybe we should --- support loading Pixmaps without exposing them. +-- 'Image' is a \"no window\" widget (has no \"Gdk Window\" of its own), so by +-- default does not receive events. If you want to receive events on the image, +-- such as button clicks, place the image inside a 'EventBox', then connect to +-- the event signals on the event box. -- -module Graphics.UI.Gtk.Display.Image ( +-- When handling events on the event box, keep in mind that coordinates in +-- the image may be different from event box coordinates due to the alignment +-- and padding settings on the image (see 'Misc'). The simplest way to solve +-- this is to set the alignment to 0.0 (left\/top), and set the padding to +-- zero. Then the origin of the image will be the same as the origin of the +-- event box. +-- +-- Sometimes an application will want to avoid depending on external data +-- files, such as image files. Gtk+ comes with a program to avoid this, called +-- gdk-pixbuf-csource. This program allows you to convert an image into a C +-- variable declaration, which can then be loaded into a 'Pixbuf' using +-- 'pixbufNewFromInline'. + +-- * Class Hierarchy +-- | +-- @ +-- | 'GObject' +-- | +----'Object' +-- | +----'Widget' +-- | +----'Misc' +-- | +----Image +-- @ + +-- * Types Image, ImageClass, castToImage, + +-- * Constructors imageNewFromFile, + imageNewFromPixbuf, + imageNewFromStock, + +-- * Methods + imageGetPixbuf, + imageSetFromPixbuf, + +-- * Icon Sizes IconSize, iconSizeMenu, iconSizeSmallToolbar, iconSizeLargeToolbar, iconSizeButton, iconSizeDialog, - imageNewFromStock, - imageGetPixbuf, - imageSetFromPixbuf, - imageNewFromPixbuf ) where import Monad (liftM) @@ -70,7 +123,8 @@ {# context lib="gtk" prefix="gtk" #} --- methods +-------------------- +-- Constructors -- | Create an image by loading a file. -- @@ -82,6 +136,13 @@ withUTFString path {#call unsafe image_new_from_file#} #endif +-- | Create an 'Image' from a +-- 'Pixbuf'. +-- +imageNewFromPixbuf :: Pixbuf -> IO Image +imageNewFromPixbuf pbuf = makeNewObject mkImage $ liftM castPtr $ + {#call unsafe image_new_from_pixbuf#} pbuf + -- | Create a set of images by specifying a stock -- object. -- @@ -90,6 +151,9 @@ makeNewObject mkImage $ liftM castPtr $ {#call unsafe image_new_from_stock#} strPtr (fromIntegral ic) +-------------------- +-- Methods + -- | Extract the Pixbuf from the 'Image'. -- imageGetPixbuf :: Image -> IO Pixbuf @@ -97,15 +161,7 @@ throwIfNull "Image.imageGetPixbuf: The image contains no Pixbuf object." $ {#call unsafe image_get_pixbuf#} img - -- | Overwrite the current content of the 'Image' with a new 'Pixbuf'. -- imageSetFromPixbuf :: Image -> Pixbuf -> IO () imageSetFromPixbuf img pb = {#call unsafe gtk_image_set_from_pixbuf#} img pb - --- | Create an 'Image' from a --- 'Pixbuf'. --- -imageNewFromPixbuf :: Pixbuf -> IO Image -imageNewFromPixbuf pbuf = makeNewObject mkImage $ liftM castPtr $ - {#call unsafe image_new_from_pixbuf#} pbuf Index: ProgressBar.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/ProgressBar.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- ProgressBar.chs 12 Feb 2005 17:19:22 -0000 1.2 +++ ProgressBar.chs 25 Feb 2005 01:11:32 -0000 1.3 @@ -28,10 +28,50 @@ -- patient while some time intensive task is going on. -- module Graphics.UI.Gtk.Display.ProgressBar ( +-- * Description +-- +-- | The 'ProgressBar' is typically used to display the progress of a long +-- running operation. It provides a visual clue that processing is underway. +-- The 'ProgressBar' can be used in two different modes: percentage mode and +-- activity mode. +-- +-- When an application can determine how much work needs to take place (e.g. +-- read a fixed number of bytes from a file) and can monitor its progress, it +-- can use the 'ProgressBar' in percentage mode and the user sees a growing bar +-- indicating the percentage of the work that has been completed. In this mode, +-- the application is required to call 'progressBarSetFraction' periodically to +-- update the progress bar. +-- +-- When an application has no accurate way of knowing the amount of work to +-- do, it can use the 'ProgressBar' in activity mode, which shows activity by a +-- block moving back and forth within the progress area. In this mode, the +-- application is required to call 'progressBarPulse' perodically to update the +-- progress bar. +-- +-- There is quite a bit of flexibility provided to control the appearance of +-- the 'ProgressBar'. Functions are provided to control the orientation of the +-- bar, optional text can be displayed along with the bar, and the step size +-- used in activity mode can be set. + +-- * Class Hierarchy +-- | +-- @ +-- | 'GObject' +-- | +----'Object' +-- | +----'Widget' +-- | +----'Progress' +-- | +----ProgressBar +-- @ + +-- * Types ProgressBar, ProgressBarClass, castToProgressBar, + +-- * Constructors progressBarNew, + +-- * Methods progressBarPulse, progressBarSetText, progressBarSetFraction, @@ -55,7 +95,8 @@ {# context lib="gtk" prefix="gtk" #} --- methods +-------------------- +-- Constructors -- | Create a new ProgreeBar. -- @@ -63,6 +104,9 @@ progressBarNew = makeNewObject mkProgressBar $ liftM castPtr $ {#call unsafe progress_bar_new#} +-------------------- +-- Methods + -- | Indicates that some progress is made, but you -- don't know how much. Causes the progress bar to enter \`activity mode', -- where a block bounces back and forth. Each call to @@ -141,4 +185,3 @@ progressBarGetOrientation pb = liftM (toEnum.fromIntegral) $ {#call unsafe progress_bar_get_orientation#} (toProgressBar pb) - Index: Statusbar.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/Statusbar.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- Statusbar.chs 12 Feb 2005 17:19:22 -0000 1.2 +++ Statusbar.chs 25 Feb 2005 01:11:32 -0000 1.3 @@ -26,36 +26,64 @@ -- -- Report messages of minor importance to the user. -- --- * A Statusbar is usually placed along the bottom of an application's main --- Window. It may provide a regular commentary of the application's status --- (as is usually the case in a web browser, for example), or may be used to --- simply output a message when the status changes, (when an upload is --- complete in an FTP client, for example). +module Graphics.UI.Gtk.Display.Statusbar ( +-- * Description +-- +-- | A 'Statusbar' is usually placed along the bottom of an application's main +-- 'Window'. It may provide a regular commentary of the application's status +-- (as is usually the case in a web browser, for example), or may be used to +-- simply output a message when the status changes, (when an upload is complete +-- in an FTP client, for example). It may also have a resize grip (a triangular +-- area in the lower right corner) which can be clicked on to resize the window +-- containing the statusbar. -- --- * Status bars in Gtk+ maintain a stack of messages. The message at the top --- of the each bar's stack is the one that will currently be displayed. --- Any messages added to a statusbar's stack must specify a ContextId that --- is used to uniquely identify the source of a message. This ContextId can --- be generated by statusbarGetContextId, given a message and the statusbar --- that it will be added to. Note that messages are stored in a stack, and --- when choosing which message to display, the stack structure is adhered --- to, regardless of the context identifier of a message. --- Messages are added to the bar's stack with statusbarPush. The message at --- the top of the stack can be removed using statusbarPop. A message can be --- removed from anywhere in the stack if it's MessageId was recorded at the --- time it was added. This is done using statusbarRemove. +-- Status bars in Gtk+ maintain a stack of messages. The message at the top +-- of the each bar's stack is the one that will currently be displayed. -- -module Graphics.UI.Gtk.Display.Statusbar ( +-- Any messages added to a statusbar's stack must specify a /context_id/ +-- that is used to uniquely identify the source of a message. This context_id +-- can be generated by 'statusbarGetContextId', given a message and the +-- statusbar that it will be added to. Note that messages are stored in a +-- stack, and when choosing which message to display, the stack structure is +-- adhered to, regardless of the context identifier of a message. +-- +-- Status bars are created using 'statusbarNew'. +-- +-- Messages are added to the bar's stack with 'statusbarPush'. +-- +-- The message at the top of the stack can be removed using 'statusbarPop'. +-- A message can be removed from anywhere in the stack if its message_id was +-- recorded at the time it was added. This is done using 'statusbarRemove'. + +-- * Class Hierarchy +-- | +-- @ +-- | 'GObject' +-- | +----'Object' +-- | +----'Widget' +-- | +----'Container' +-- | +----'Box' +-- | +----'HBox' +-- | +----Statusbar +-- @ + +-- * Types Statusbar, StatusbarClass, castToStatusbar, + +-- * Constructors statusbarNew, + +-- * Methods statusbarGetContextId, statusbarPush, statusbarPop, statusbarRemove, statusbarSetHasResizeGrip, statusbarGetHasResizeGrip, + +-- * Signals onTextPopped, afterTextPopped, onTextPushed, @@ -72,7 +100,8 @@ {# context lib="gtk" prefix="gtk" #} --- methods +-------------------- +-- Constructors -- | Create a new Statusbar. -- @@ -80,6 +109,9 @@ statusbarNew = makeNewObject mkStatusbar $ liftM castPtr {#call unsafe statusbar_new#} +-------------------- +-- Methods + type ContextId = {#type guint#} -- | Given a context description, this function @@ -124,7 +156,8 @@ statusbarGetHasResizeGrip sb = liftM toBool $ {#call unsafe statusbar_get_has_resize_grip#} (toStatusbar sb) --- signals +-------------------- +-- Signals -- | Called if a message is removed. -- Index: AccelLabel.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/AccelLabel.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- AccelLabel.chs 12 Feb 2005 17:19:21 -0000 1.2 +++ AccelLabel.chs 25 Feb 2005 01:11:32 -0000 1.3 @@ -24,17 +24,55 @@ -- Stability : provisional -- Portability : portable (depends on GHC) -- --- This widget is a special version of 'Label'. It displays an --- accelerator key next to the Label. --- --- * The key name is not explicitly set but taken from the key that --- is associated with the activation of another widget. +-- A label which displays an accelerator key on the right of the text. -- module Graphics.UI.Gtk.Display.AccelLabel ( +-- * Description +-- +-- | The 'AccelLabel' widget is a subclass of 'Label' that also displays an +-- accelerator key on the right of the label text, e.g. \'Ctl+S\'. It is +-- commonly used in menus to show the keyboard short-cuts for commands. +-- +-- The accelerator key to display is not set explicitly. Instead, the +-- 'AccelLabel' displays the accelerators which have been added to a particular +-- widget. This widget is set by calling 'accelLabelSetAccelWidget'. +-- +-- For example, a 'MenuItem' widget may have an accelerator added to emit +-- the \"activate\" signal when the \'Ctl+S\' key combination is pressed. A +-- 'AccelLabel' is created and added to the 'MenuItem', and +-- 'accelLabelSetAccelWidget' is called with the 'MenuItem' as the second +-- argument. The 'AccelLabel' will now display \'Ctl+S\' after its label. +-- +-- Note that creating a 'MenuItem' with 'menuItemNewWithLabel' (or one of +-- the similar functions for 'CheckMenuItem' and 'RadioMenuItem') automatically +-- adds a 'AccelLabel' to the 'MenuItem' and calls 'accelLabelSetAccelWidget' +-- to set it up for you. +-- +-- A 'AccelLabel' will only display accelerators which have 'AccelVisible' +-- set (see 'AccelFlags'). A 'AccelLabel' can display multiple accelerators and +-- even signal names, though it is almost always used to display just one +-- accelerator key. + +-- * Class Hierarchy +-- | +-- @ +-- | 'GObject' +-- | +----'Object' +-- | +----'Widget' +-- | +----'Misc' +-- | +----'Label' +-- | +----AccelLabel +-- @ + +-- * Types AccelLabel, AccelLabelClass, castToAccelLabel, + +-- * Constructors accelLabelNew, + +-- * Methods accelLabelSetAccelWidget, accelLabelGetAccelWidget ) where @@ -49,7 +87,8 @@ {# context lib="gtk" prefix="gtk" #} --- methods +-------------------- +-- Constructors -- | Create a new label with an accelerator key. -- @@ -57,6 +96,9 @@ accelLabelNew str = withUTFString str $ \strPtr -> makeNewObject mkAccelLabel $ liftM castPtr $ {#call unsafe accel_label_new#} strPtr +-------------------- +-- Methods + -- | Set the key name from the activation -- signal of another widget. -- Index: Label.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Display/Label.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- Label.chs 12 Feb 2005 17:19:22 -0000 1.2 +++ Label.chs 25 Feb 2005 01:11:32 -0000 1.3 @@ -27,11 +27,100 @@ -- A widget that displays a small to medium amount of text. -- module Graphics.UI.Gtk.Display.Label ( +-- * Description +-- +-- | The 'Label' widget displays a small amount of text. As the name implies, +-- most labels are used to label another widget such as a 'Button', a +-- 'MenuItem', or a 'OptionMenu'. + +-- ** Mnemonics +-- +-- | Labels may contain mnemonics. Mnemonics are underlined characters in the +-- label, used for keyboard navigation. Mnemonics are created by providing a +-- string with an underscore before the mnemonic character, such as +-- @\"_File\"@, to the functions 'labelNewWithMnemonic' or +-- 'labelSetTextWithMnemonic'. +-- +-- Mnemonics automatically activate any activatable widget the label is +-- inside, such as a 'Button'; if the label is not inside the mnemonic's target +-- widget, you have to tell the label about the target using +-- 'labelSetMnemonicWidget'. Here's a simple example where the label is inside +-- a button: There's a convenience function to create buttons with a mnemonic +-- label already inside: To create a mnemonic for a widget alongside the label, +-- such as a 'Entry', you have to point the label at the entry with +-- 'labelSetMnemonicWidget': +-- +-- > -- Pressing Alt+H will activate this button +-- > button <- buttonNew +-- > label <- labelNewWithMnemonic "_Hello" +-- > containerAdd button label +-- +-- > -- Pressing Alt+H will activate this button +-- > button <- buttonNewWithMnemonic "_Hello" +-- +-- > -- Pressing Alt+H will focus the entry +-- > entry <- entryNew +-- > label <- labelNewWithMnemonic "_Hello" +-- > labelSetMnemonicWidget label entry + +-- ** Markup (styled text) +-- +-- | To make it easy to format text in a label (changing colors, fonts, etc.), +-- label text can be provided in a simple markup format. Here's how to create a +-- label with a small font: (See complete documentation of available tags in +-- the Pango manual.) +-- +-- > label <- labelNew Nothing +-- > labelSetMarkup label "<small>Small text</small>" +-- +-- The markup passed to 'labelSetMarkup' must be valid; for example, literal +-- \<\/>\/& characters must be escaped as @\"<\"@, @\">\"@, and +-- @\"&@\". If you pass +-- text obtained from the user, file, or a network to 'labelSetMarkup', you\'ll +-- want to escape it with 'gMarkupEscapeText'. + +-- ** Selectable labels +-- +-- | Labels can be made selectable with 'labelSetSelectable'. Selectable +-- labels allow the user to copy the label contents to the clipboard. Only +-- labels that contain useful-to-copy information - such as error messages - +-- should be made selectable. + +-- ** Text layout +-- +-- | A label can contain any number of paragraphs, but will have performance +-- problems if it contains more than a small number. Paragraphs are separated +-- by newlines or other paragraph separators understood by Pango. +-- +-- Labels can automatically wrap text if you call 'labelSetLineWrap'. +-- +-- 'labelSetJustify' sets how the lines in a label align with one another. +-- If you want to set how the label as a whole aligns in its available space, +-- see 'miscSetAlignment'. +-- + +-- * Class Hierarchy +-- | +-- @ +-- | 'GObject' +-- | +----'Object' +-- | +----'Widget' +-- | +----'Misc' +-- | +----Label +-- | +----'AccelLabel' +-- | +----'TipsQuery' +-- @ + +-- * Types Label, LabelClass, castToLabel, + +-- * Constructors labelNew, labelNewWithMnemonic, + +-- * Methods labelSetText, labelSetLabel, labelSetTextWithMnemonic, @@ -74,8 +163,8 @@ import Graphics.UI.Gtk.Pango.Markup {# context lib="gtk" prefix="gtk" #} - --- methods +-------------------- +-- Constructors -- | Create a new label widget. -- @@ -85,6 +174,19 @@ Nothing -> {#call label_new#} nullPtr (Just str) -> withUTFString str {#call label_new#} +-- | Create a new label widget with accelerator key. +-- +-- * Each underscore in @str@ is converted into an underlined character in the +-- label. Entering this character will activate the label widget or any other +-- widget set with 'labelSetMnemonicWidget'. +-- +labelNewWithMnemonic :: String -> IO Label +labelNewWithMnemonic str = makeNewObject mkLabel $ liftM castPtr $ + withUTFString str {#call label_new_with_mnemonic#} + +-------------------- +-- Methods + -- | Set the text the label widget shows. -- labelSetText :: LabelClass l => l -> String -> IO () @@ -222,16 +324,6 @@ labelGetLabel :: LabelClass l => l -> IO String labelGetLabel l = {#call unsafe label_get_label#} (toLabel l) >>= peekUTFString --- | Create a new label widget with accelerator key. --- --- * Each underscore in @str@ is converted into an underlined character in the --- label. Entering this character will activate the label widget or any other --- widget set with 'labelSetMnemonicWidget'. --- -labelNewWithMnemonic :: String -> IO Label -labelNewWithMnemonic str = makeNewObject mkLabel $ liftM castPtr $ - withUTFString str {#call label_new_with_mnemonic#} - -- | Select a region in the label. -- labelSelectRegion :: LabelClass l => l -> Int -> Int -> IO () |
