Migrating to Adaptive Dialogs

Migrating to Adaptive Dialogs

Libadapta 1.5 introduces AdapDialog and replacements for AdapMessageDialog, AdapPreferencesWindow and AdapAboutWindow that derive from it.

While the old widgets are not deprecated yet, they will be in the next release.

Use AdapWindow or AdapApplicationWindow for the Parent Window

To use AdapDialog, your parent window must be an instance of either AdapWindow or AdapApplicationWindow. You should migrate to these widgets if you’re still using GtkWindow or GtkApplicationWindow, respectively.

Stop using window titlebar, instead, create an AdapToolbarView and add the titlebar to it as a top bar. Set the window child as the toolbar view content. Set the toolbar view as the AdapWindow:content property on the window.

If you have GtkSearchBar, GtkActionBar etc in a GtkBox, move them to the toolbar view as well as top/bottom bars respectively.

Example:

<object class="GtkWindow">
  <property name="titlebar">
    <object class="AdapHeaderBar"/>
  </property>
  <property name="child">
    <object class="GtkBox">
      <property name="orientation">vertical</property>
      <child>
        <!-- content -->
      </child>
      <child>
        <object class="GtkActionBar"/>
      </child>
    </object>
  </property>
</object>

becomes this:

<object class="AdapWindow">
  <property name="content">
    <object class="AdapToolbarView">
      <child type="top">
        <object class="AdapHeaderBar"/>
      </child>
      <property name="content">
        <!-- content -->
      </property>
      <child type="bottom">
        <object class="GtkActionBar"/>
      </child>
    </object>
  </property>
</object>

Porting to AdapDialog

The API of AdapDialog is somewhat like a subset of the API of AdapWindow.

GtkWindow AdapDialog
GtkWindow:child AdapDialog:child
GtkWindow:title AdapDialog:title
GtkWindow:default-width AdapDialog:content-width
GtkWindow:default-height AdapDialog:content-height
GtkWindow:resizable AdapDialog:follows-content-size
GtkWindow:focus-widget AdapDialog:focus-widget
GtkWindow:default-widget AdapDialog:default-widget
gtk_window_close() adap_dialog_close()
gtk_window_destroy() adap_dialog_force_close()
gtk_window_present() adap_dialog_present()
AdapWindow AdapDialog
AdapWindow:content AdapDialog:child
AdapWindow:current-breakpoint AdapDialog:current-breakpoint
adap_window_add_breakpoint() adap_dialog_add_breakpoint()

Since these dialogs are within the parent window, they are always destroyed with parent, so there’s no replacement for GtkWindow:destroy-with-parent.

GtkWindow sizing can behave in two ways: when resizable, its size is controlled with GtkWindow:default-width and GtkWindow:default-height. If the content shrinks, the window keeps the size it had before. If the content grows, the window grows with it. When not resizable, it follows the content’s size precisely.

While dialogs are not resizable, they can behave in both ways as well. By default, their size is controlled with AdapDialog:content-width and AdapDialog:content-height, like for resizable windows. Set AdapDialog:follows-content-size to FALSE to follow the content size precisely, like for non-resizable windows.

Since the dialog size is constrained by the parent window, you may want to adjust the content sizes. For example, if it had a small default height just so it doesn’t grow larger than its parent window, that can be increased or removed.

Dialogs are regular widgets, so they can be closed and presented again endlessly as long as you hold a reference to them. If you were setting the GtkWindow:hide-on-close property to TRUE, do that instead.

Dialogs are always modal. The GtkWindow:transient-for property is replaced by a parameter in adap_dialog_present().

Tip

The widget passed into adap_dialog_present() doesn’t have to be a window. You can pass any widget within a window to get the same effect as passing the window itself. This is done both for convenience and to allow for more flexibility in future.

GtkWindow::close-request doesn’t have a direct replacement. When presented as a bottom sheet, dialogs can be swiped down, and because of that you have to specify whether the dialog can be closed right now ahead of time.

  • If you were using ::close-request to completely prevent window closing, set the AdapDialog:can-close property to FALSE.
  • To have a close confirmation, use the AdapDialog::close-attempt signal.
  • adap_dialog_force_close() closes the dialog even when :can-close is set to FALSE, and can be used to close the dialog after the confirmation.
  • If you were using ::close-request just to track when the window is closed, use the AdapDialog::closed signal instead.

Use AdapHeaderBar Instead of GtkHeaderBar

AdapHeaderBar will use the dialog’s title and adjust decoration layout to always include a close button and nothing else. Since GtkHeaderBar doesn’t do this, the dialog will not behave correctly.

Replace your GtkHeaderBar with AdapHeaderBar, and GtkHeaderBar:show-title-buttons with a combination of AdapHeaderBar:show-start-title-buttons and AdapHeaderBar:show-end-title-buttons.

Remove Close Shortcut

AdapDialog can be closed by pressing Esc. If you were handling that manually, you can stop doing it.

Port AdapAboutWindow to AdapAboutDialog

AdapAboutDialog has identical API to AdapAboutWindow, so just replace the function calls as appropriate - for example, adap_about_window_add_link() with adap_about_dialog_add_link() and so on.

Port AdapPreferencesWindow to AdapPreferencesDialog

AdapPreferencesDialog has very similar API to AdapPreferencesWindow, and only needs a few adjustments.

Stop Using Deprecated API

The deprecated subpage API has been removed. Refer to the breakpoints migration guide for information on how to replace it.

Adapt to Search Changes

AdapPreferencesDialog changes the default of the AdapPreferencesWindow:search-enabled property to FALSE.

If you want search, make sure to set it to TRUE manually, and if you were disabling it, you can stop doing so.

Otherwise, replace the function calls as appropriate, for example adap_preferences_window_add_toast() with adap_preferences_dialog_add_toast() and so on.

Port AdapMessageDialog to AdapAlertDialog

AdapAlertDialog has mostly similar API to AdapMessageDialog.

Adapt to Constructor Changes

adap_alert_dialog_new() doesn’t accept a parent window anymore, so remove that parameter. Instead, pass it as a parameter to adap_dialog_present() or adap_alert_dialog_choose().

Adapt to adap_alert_dialog_choose() Changes

Just like adap_dialog_present(), adap_alert_dialog_choose() now takes the parent widget as a parameter.

Tip

The widget passed into adap_alert_dialog_choose() doesn’t have to be a window. You can pass any widget within a window to get the same effect as passing the window itself. This is done both for convenience and to allow for more flexibility in future.

Stop Using adap_message_dialog_response()

adap_message_dialog_response() has no replacement. Most applications shouldn’t be using it in the first place, but if you really do, emit the AdapAlertDialog::response signal manually instead.

Otherwise, replace the function calls as appropriate, for example adap_message_dialog_add_response() with adap_alert_dialog_add_response() and so on.

Adapt to Scrolling

AdapAlertDialog can scroll its content. If you were setting a GtkScrolledWindow as AdapMessageDialog:extra-child, you may want to remove the scrolled window and use its contents directly.