gi-gtk-3.0.43: Gtk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.FileChooserDialog

Contents

- Exported types
- Methods

Description

`FileChooserDialog` is a dialog box suitable for use with “File/Open” or “File/Save as” commands. This widget works by putting a `FileChooserWidget` inside a `Dialog`. It exposes the `FileChooser` interface, so you can use all of the `FileChooser` functions on the file chooser dialog as well as those for `Dialog`.

Note that `FileChooserDialog` does not have any methods of its own. Instead, you should use the functions that work on a `FileChooser`.

If you want to integrate well with the platform you should use the `FileChooserNative` API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise.

## Typical usage ## {`gtkfilechooser`-typical-usage}

In the simplest of cases, you can the following code to use `FileChooserDialog` to select a file for opening:

    GtkWidget *dialog;
    GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
    gint res;

    dialog = gtk_file_chooser_dialog_new ("Open File",
                                          parent_window,
                                          action,
                                          _("_Cancel"),
                                          GTK_RESPONSE_CANCEL,
                                          _("_Open"),
                                          GTK_RESPONSE_ACCEPT,
                                          NULL);

    res = gtk_dialog_run (GTK_DIALOG (dialog));
    if (res == GTK_RESPONSE_ACCEPT)
      {
        char *filename;
        GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
        filename = gtk_file_chooser_get_filename (chooser);
        open_file (filename);
        g_free (filename);
      }

    gtk_widget_destroy (dialog);

To use a dialog for saving, you can use this:

    GtkWidget *dialog;
    GtkFileChooser *chooser;
    GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
    gint res;

    dialog = gtk_file_chooser_dialog_new ("Save File",
                                          parent_window,
                                          action,
                                          _("_Cancel"),
                                          GTK_RESPONSE_CANCEL,
                                          _("_Save"),
                                          GTK_RESPONSE_ACCEPT,
                                          NULL);
    chooser = GTK_FILE_CHOOSER (dialog);

    gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

    if (user_edited_a_new_document)
      gtk_file_chooser_set_current_name (chooser,
                                         _("Untitled document"));
    else
      gtk_file_chooser_set_filename (chooser,
                                     existing_filename);

    res = gtk_dialog_run (GTK_DIALOG (dialog));
    if (res == GTK_RESPONSE_ACCEPT)
      {
        char *filename;

        filename = gtk_file_chooser_get_filename (chooser);
        save_to_file (filename);
        g_free (filename);
      }

    gtk_widget_destroy (dialog);

## Setting up a file chooser dialog ## {`gtkfilechooserdialog`-setting-up}

There are various cases in which you may need to use a `FileChooserDialog`:

- To select a file for opening. Use `GTK_FILE_CHOOSER_ACTION_OPEN`.
- To save a file for the first time. Use `GTK_FILE_CHOOSER_ACTION_SAVE`, and suggest a name such as “Untitled” with `fileChooserSetCurrentName`.
- To save a file under a different name. Use `GTK_FILE_CHOOSER_ACTION_SAVE`, and set the existing filename with `fileChooserSetFilename`.
- To choose a folder instead of a file. Use `GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER`.

Note that old versions of the file chooser’s documentation suggested using `fileChooserSetCurrentFolder` in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use `fileChooserSetFilename`, i.e. when you are doing a Save As command and you already have a file saved somewhere.

## Response Codes ## {`gtkfilechooserdialog`-responses}

`FileChooserDialog` inherits from `Dialog`, so buttons that go in its action area have response codes such as `GTK_RESPONSE_ACCEPT` and `GTK_RESPONSE_CANCEL`. For example, you could call `gtk_file_chooser_dialog_new()` as follows:

    GtkWidget *dialog;
    GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

    dialog = gtk_file_chooser_dialog_new ("Open File",
                                          parent_window,
                                          action,
                                          _("_Cancel"),
                                          GTK_RESPONSE_CANCEL,
                                          _("_Open"),
                                          GTK_RESPONSE_ACCEPT,
                                          NULL);

This will create buttons for “Cancel” and “Open” that use stock response identifiers from `ResponseType`. For most dialog boxes you can use your own custom response codes rather than the ones in `ResponseType`, but `FileChooserDialog` assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

-     GTK_RESPONSE_ACCEPT

-     GTK_RESPONSE_OK

-     GTK_RESPONSE_YES

-     GTK_RESPONSE_APPLY

This is because `FileChooserDialog` must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate.

To summarize, make sure you use a [stock response code][gtkfilechooserdialog-responses] when you use `FileChooserDialog` to ensure proper operation.

Synopsis

- newtype FileChooserDialog = FileChooserDialog (ManagedPtr FileChooserDialog)
- class (GObject o, IsDescendantOf FileChooserDialog o) => IsFileChooserDialog o
- toFileChooserDialog :: (MonadIO m, IsFileChooserDialog o) => o -> m FileChooserDialog

# Exported types

newtype FileChooserDialog Source #

Memory-managed wrapper type.

Constructors

FileChooserDialog (ManagedPtr FileChooserDialog) |

#### Instances

Instances details

Eq FileChooserDialog Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog Methods (==) :: FileChooserDialog -> FileChooserDialog -> Bool Source # (/=) :: FileChooserDialog -> FileChooserDialog -> Bool Source #
GObject FileChooserDialog Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog
ManagedPtrNewtype FileChooserDialog Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog Methods toManagedPtr :: FileChooserDialog -> ManagedPtr FileChooserDialog Source #
TypedObject FileChooserDialog Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog Methods glibType :: IO GType Source #
HasParentTypes FileChooserDialog Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog
IsGValue (Maybe FileChooserDialog) Source # | Convert `FileChooserDialog` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.FileChooserDialog Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe FileChooserDialog -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe FileChooserDialog) Source #
type ParentTypes FileChooserDialog Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog type ParentTypes FileChooserDialog = '[Dialog, Window, Bin, Container, Widget, Object, ImplementorIface, Buildable, FileChooser]

class (GObject o, IsDescendantOf FileChooserDialog o) => IsFileChooserDialog o Source #

Type class for types which can be safely cast to `FileChooserDialog`, for instance with `toFileChooserDialog`.

#### Instances

Instances details

(GObject o, IsDescendantOf FileChooserDialog o) => IsFileChooserDialog o Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserDialog

toFileChooserDialog :: (MonadIO m, IsFileChooserDialog o) => o -> m FileChooserDialog Source #

Cast to `FileChooserDialog`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

activate, activateDefault, activateFocus, activateKey, add, addAccelGroup, addAccelerator, addActionWidget, addButton, addChild, addChoice, addDeviceEvents, addEvents, addFilter, addMnemonic, addMnemonicLabel, addShortcutFolder, addShortcutFolderUri, addTickCallback, beginMoveDrag, beginResizeDrag, bindProperty, bindPropertyFull, canActivateAccel, checkResize, childFocus, childGetProperty, childNotify, childNotifyByPspec, childSetProperty, childType, classPath, close, computeExpand, constructChild, createPangoContext, createPangoLayout, customFinished, customTagEnd, customTagStart, deiconify, destroy, destroyed, deviceIsShadowed, dragBegin, dragBeginWithCoordinates, dragCheckThreshold, dragDestAddImageTargets, dragDestAddTextTargets, dragDestAddUriTargets, dragDestFindTarget, dragDestGetTargetList, dragDestGetTrackMotion, dragDestSet, dragDestSetProxy, dragDestSetTargetList, dragDestSetTrackMotion, dragDestUnset, dragGetData, dragHighlight, dragSourceAddImageTargets, dragSourceAddTextTargets, dragSourceAddUriTargets, dragSourceGetTargetList, dragSourceSet, dragSourceSetIconGicon, dragSourceSetIconName, dragSourceSetIconPixbuf, dragSourceSetIconStock, dragSourceSetTargetList, dragSourceUnset, dragUnhighlight, draw, ensureStyle, errorBell, event, forall, forceFloating, foreach, freezeChildNotify, freezeNotify, fullscreen, fullscreenOnMonitor, getv, grabAdd, grabDefault, grabFocus, grabRemove, hasDefault, hasFocus, hasGrab, hasGroup, hasRcStyle, hasScreen, hasToplevelFocus, hasVisibleFocus, hide, hideOnDelete, iconify, inDestruction, initTemplate, inputShapeCombineRegion, insertActionGroup, intersect, isActive, isAncestor, isComposited, isDrawable, isFloating, isFocus, isMaximized, isSensitive, isToplevel, isVisible, keynavFailed, listAccelClosures, listActionPrefixes, listFilters, listMnemonicLabels, listShortcutFolderUris, listShortcutFolders, map, maximize, mnemonicActivate, modifyBase, modifyBg, modifyCursor, modifyFg, modifyFont, modifyStyle, modifyText, move, notify, notifyByPspec, overrideBackgroundColor, overrideColor, overrideCursor, overrideFont, overrideSymbolicColor, parseGeometry, parserFinished, path, present, presentWithTime, propagateDraw, propagateKeyEvent, queueAllocate, queueComputeExpand, queueDraw, queueDrawArea, queueDrawRegion, queueResize, queueResizeNoRedraw, realize, ref, refSink, regionIntersect, registerWindow, remove, removeAccelGroup, removeAccelerator, removeChoice, removeFilter, removeMnemonic, removeMnemonicLabel, removeShortcutFolder, removeShortcutFolderUri, removeTickCallback, renderIcon, renderIconPixbuf, reparent, resetRcStyles, resetStyle, reshowWithInitialSize, resize, resizeChildren, resizeGripIsVisible, resizeToGeometry, response, run, runDispose, selectAll, selectFile, selectFilename, selectUri, sendExpose, sendFocusChange, shapeCombineRegion, show, showAll, showNow, sizeAllocate, sizeAllocateWithBaseline, sizeRequest, stealData, stealQdata, stick, styleAttach, styleGetProperty, thawChildNotify, thawNotify, translateCoordinates, triggerTooltipQuery, unfullscreen, unmap, unmaximize, unparent, unrealize, unref, unregisterWindow, unselectAll, unselectFile, unselectFilename, unselectUri, unsetFocusChain, unsetStateFlags, unstick, watchClosure.

#### Getters

getAcceptFocus, getAccessible, getAction, getActionArea, getActionGroup, getAllocatedBaseline, getAllocatedHeight, getAllocatedSize, getAllocatedWidth, getAllocation, getAncestor, getAppPaintable, getApplication, getAttachedTo, getBorderWidth, getCanDefault, getCanFocus, getChild, getChildRequisition, getChildVisible, getChildren, getChoice, getClip, getClipboard, getCompositeName, getContentArea, getCreateFolders, getCurrentFolder, getCurrentFolderFile, getCurrentFolderUri, getCurrentName, getData, getDecorated, getDefaultSize, getDefaultWidget, getDeletable, getDestroyWithParent, getDeviceEnabled, getDeviceEvents, getDirection, getDisplay, getDoOverwriteConfirmation, getDoubleBuffered, getEvents, getExtraWidget, getFile, getFilename, getFilenames, getFiles, getFilter, getFocus, getFocusChain, getFocusChild, getFocusHadjustment, getFocusOnClick, getFocusOnMap, getFocusVadjustment, getFocusVisible, getFontMap, getFontOptions, getFrameClock, getGravity, getGroup, getHalign, getHasResizeGrip, getHasTooltip, getHasWindow, getHeaderBar, getHexpand, getHexpandSet, getHideTitlebarWhenMaximized, getIcon, getIconList, getIconName, getInternalChild, getLocalOnly, getMapped, getMarginBottom, getMarginEnd, getMarginLeft, getMarginRight, getMarginStart, getMarginTop, getMnemonicModifier, getMnemonicsVisible, getModal, getModifierMask, getModifierStyle, getName, getNoShowAll, getOpacity, getPangoContext, getParent, getParentWindow, getPath, getPathForChild, getPointer, getPosition, getPreferredHeight, getPreferredHeightAndBaselineForWidth, getPreferredHeightForWidth, getPreferredSize, getPreferredWidth, getPreferredWidthForHeight, getPreviewFile, getPreviewFilename, getPreviewUri, getPreviewWidget, getPreviewWidgetActive, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRequisition, getResizable, getResizeGripArea, getResizeMode, getResponseForWidget, getRole, getRootWindow, getScaleFactor, getScreen, getSelectMultiple, getSensitive, getSettings, getShowHidden, getSize, getSizeRequest, getSkipPagerHint, getSkipTaskbarHint, getState, getStateFlags, getStyle, getStyleContext, getSupportMultidevice, getTemplateChild, getTitle, getTitlebar, getTooltipMarkup, getTooltipText, getTooltipWindow, getToplevel, getTransientFor, getTypeHint, getUrgencyHint, getUri, getUris, getUsePreviewLabel, getValign, getValignWithBaseline, getVexpand, getVexpandSet, getVisible, getVisual, getWidgetForResponse, getWindow, getWindowType.

#### Setters

setAccelPath, setAcceptFocus, setAction, setAllocation, setAlternativeButtonOrderFromArray, setAppPaintable, setApplication, setAttachedTo, setBorderWidth, setBuildableProperty, setCanDefault, setCanFocus, setChildVisible, setChoice, setClip, setCompositeName, setCreateFolders, setCurrentFolder, setCurrentFolderFile, setCurrentFolderUri, setCurrentName, setData, setDataFull, setDecorated, setDefault, setDefaultGeometry, setDefaultResponse, setDefaultSize, setDeletable, setDestroyWithParent, setDeviceEnabled, setDeviceEvents, setDirection, setDoOverwriteConfirmation, setDoubleBuffered, setEvents, setExtraWidget, setFile, setFilename, setFilter, setFocus, setFocusChain, setFocusChild, setFocusHadjustment, setFocusOnClick, setFocusOnMap, setFocusVadjustment, setFocusVisible, setFontMap, setFontOptions, setGeometryHints, setGravity, setHalign, setHasResizeGrip, setHasTooltip, setHasUserRefCount, setHasWindow, setHexpand, setHexpandSet, setHideTitlebarWhenMaximized, setIcon, setIconFromFile, setIconList, setIconName, setKeepAbove, setKeepBelow, setLocalOnly, setMapped, setMarginBottom, setMarginEnd, setMarginLeft, setMarginRight, setMarginStart, setMarginTop, setMnemonicModifier, setMnemonicsVisible, setModal, setName, setNoShowAll, setOpacity, setParent, setParentWindow, setPosition, setPreviewWidget, setPreviewWidgetActive, setProperty, setRealized, setReallocateRedraws, setReceivesDefault, setRedrawOnAllocate, setResizable, setResizeMode, setResponseSensitive, setRole, setScreen, setSelectMultiple, setSensitive, setShowHidden, setSizeRequest, setSkipPagerHint, setSkipTaskbarHint, setStartupId, setState, setStateFlags, setStyle, setSupportMultidevice, setTitle, setTitlebar, setTooltipMarkup, setTooltipText, setTooltipWindow, setTransientFor, setTypeHint, setUrgencyHint, setUri, setUsePreviewLabel, setValign, setVexpand, setVexpandSet, setVisible, setVisual, setWindow, setWmclass.