help.c

Go to the documentation of this file.

/*
    This file is part of the Ansel project.
    Copyright (C) 2023, 2025-2026 Aurélien PIERRE.
    Copyright (C) 2023 Luca Zulberti.
    
    Ansel is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    Ansel is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with Ansel.  If not, see <http://www.gnu.org/licenses/>.
*/
#include "config.h" // DT_BUILD_CHANNEL, darktable_last_commit_year
#include "common/updates.h"
#include <string.h>
#include "system/mem_alloc.h"
#include "gui/application.h"
#include "widgets/accelerators.h"
#include "gui/actions/menu.h"
#ifdef __APPLE__
#include "osx/osx.h"   // dt_osx_disallow_fullscreen(), used under GDK_WINDOWING_QUARTZ below
#endif
#include "gui/actions/supervisor_window.h"
#include "control/control.h"
 
 
static gboolean show_about_dialog(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  GtkWidget *dialog = gtk_about_dialog_new();
  gtk_widget_set_name (dialog, "about-dialog");
#ifdef GDK_WINDOWING_QUARTZ
  dt_osx_disallow_fullscreen(dialog);
#endif
  gtk_about_dialog_set_program_name(GTK_ABOUT_DIALOG(dialog), PACKAGE_NAME);
  gtk_about_dialog_set_version(GTK_ABOUT_DIALOG(dialog), darktable_package_version);
  char *copyright = g_strdup_printf(_("Copyright \302\251 darktable authors 2009-2022\nCopyright \302\251 Aur\303\251lien Pierre 2022-%s"), darktable_last_commit_year);
  gtk_about_dialog_set_copyright(GTK_ABOUT_DIALOG(dialog), copyright);
  dt_free(copyright);
  gtk_about_dialog_set_comments(GTK_ABOUT_DIALOG(dialog),
                                _("Organize and develop images from digital cameras"));
  gtk_about_dialog_set_website(GTK_ABOUT_DIALOG(dialog), "https://ansel.photos");
  gtk_about_dialog_set_website_label(GTK_ABOUT_DIALOG(dialog), _("Website"));
  char *icon = g_strdup("ansel");
  gtk_about_dialog_set_logo_icon_name(GTK_ABOUT_DIALOG(dialog), icon);
  dt_free(icon);
 
  const char *str = _("all those of you that made previous releases possible");
 
#include "tools/darktable_authors.h"
 
  const char *final[] = {str, NULL };
  gtk_about_dialog_add_credit_section (GTK_ABOUT_DIALOG(dialog), _("and..."), final);
  gtk_about_dialog_set_translator_credits(GTK_ABOUT_DIALOG(dialog), _("translator-credits"));
 
  gtk_window_set_transient_for(GTK_WINDOW(dialog), GTK_WINDOW(dt_gui_main_window()));
  gtk_dialog_run(GTK_DIALOG(dialog));
  gtk_widget_destroy(dialog);
 
  return TRUE;
}
 
// Nightly builds only: opens the download for this installation's format when the
// daily check found a newer build, and the download page otherwise -- so the entry
// is useful even before the check has run, or when it is switched off.
static gboolean update_nightly_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  const char *url = dt_updates_get_download_url();
  if(!url) url = "https://ansel.photos/en/download/";
  gtk_show_uri_on_window(GTK_WINDOW(dt_gui_main_window()), url, GDK_CURRENT_TIME, NULL);
  return TRUE;
}
 
static gboolean open_doc_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  // TODO: use translated URL when doc gets translated
  gtk_show_uri_on_window(GTK_WINDOW(dt_gui_main_window()), "https://ansel.photos/en/doc", GDK_CURRENT_TIME, NULL);
  return TRUE;
}
 
static gboolean open_chat_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  gtk_show_uri_on_window(GTK_WINDOW(dt_gui_main_window()),
  "https://app.element.io/#/room/#ansel:matrix.org", GDK_CURRENT_TIME, NULL);
  return TRUE;
}
 
static gboolean open_search_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  gtk_show_uri_on_window(GTK_WINDOW(dt_gui_main_window()),
  "https://chantal.aurelienpierre.com", GDK_CURRENT_TIME, NULL);
  return TRUE;
}
 
static gboolean open_forum_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  gtk_show_uri_on_window(GTK_WINDOW(dt_gui_main_window()),
  "https://community.ansel.photos", GDK_CURRENT_TIME, NULL);
  return TRUE;
}
 
// TODO: this doesn't work for all widgets. the reason being that the GtkEventBox we put libs/iops into catches events.
static char *get_help_url(GtkWidget *widget)
{
  while(widget)
  {
    // if the widget doesn't have a help url set go up the widget hierarchy to find a parent that has an url
    gchar *help_url = g_object_get_data(G_OBJECT(widget), "dt-help-url");
    if(help_url) return help_url;
    widget = gtk_widget_get_parent(widget);
  }
 
  return NULL;
}
 
static void _restore_default_cursor()
{
  dt_control_allow_change_cursor();
  dt_control_change_cursor(GDK_LEFT_PTR);
  gdk_event_handler_set((GdkEventFunc)gtk_main_do_event, NULL, NULL);
}
 
static void _main_do_event_help(GdkEvent *event, gpointer data)
{
  gboolean handled = FALSE;
 
  switch(event->type)
  {
    case GDK_BUTTON_PRESS:
    {
      if(event->button.button == GDK_BUTTON_SECONDARY)
      {
        // On right-click : abort and reset
        _restore_default_cursor();
        handled = TRUE;
        break;
      }
 
      GtkWidget *event_widget = gtk_get_event_widget(event);
      if(event_widget)
      {
        // Note : help url contains the fully-formed URL adapted to current language
        gchar *help_url = get_help_url(event_widget);
        if(help_url && *help_url)
        {
          _restore_default_cursor();
 
          GtkWidget *win = dt_gui_main_window();
          dt_print(DT_DEBUG_CONTROL, "[context help] opening '%s'\n", help_url);
 
          // ask the user if the website may be accessed
          GtkWidget *dialog = gtk_message_dialog_new
            (GTK_WINDOW(win), GTK_DIALOG_DESTROY_WITH_PARENT,
              GTK_MESSAGE_QUESTION, GTK_BUTTONS_YES_NO,
              _("do you want to access ansel.photos ?"));
#ifdef GDK_WINDOWING_QUARTZ
            dt_osx_disallow_fullscreen(dialog);
#endif
 
          gtk_window_set_title(GTK_WINDOW(dialog), _("access the online usermanual?"));
          const gint res = gtk_dialog_run(GTK_DIALOG(dialog));
          const gboolean open = (res == GTK_RESPONSE_YES) || !(res == GTK_RESPONSE_NO);
          gtk_widget_destroy(dialog);
 
          if(open)
          {
            GError *error = NULL;
            const gboolean uri_success = gtk_show_uri_on_window(GTK_WINDOW(win), help_url, gtk_get_current_event_time(), &error);
 
            if(uri_success)
            {
              dt_control_log(_("help url opened in web browser"));
            }
            else
            {
              dt_control_log(_("error while opening help url in web browser"));
              if (!IS_NULL_PTR(error)) // uri_success being FALSE should guarantee that
              {
                fprintf (stderr, "unable to read file: %s\n", error->message);
                g_error_free(error);
              }
            }
          }
        }
        else
        {
          dt_control_log(_("there is no help available for this element"));
        }
      }
      handled = TRUE;
      break;
    }
 
    case GDK_ENTER_NOTIFY:
    case GDK_LEAVE_NOTIFY:
    {
      GtkWidget *event_widget = gtk_get_event_widget(event);
      if(event_widget)
      {
        gchar *help_url = get_help_url(event_widget);
        if(help_url)
        {
          // TODO: find a better way to tell the user that the hovered widget has a help link
          dt_cursor_t cursor = event->type == GDK_ENTER_NOTIFY ? GDK_QUESTION_ARROW : GDK_X_CURSOR;
          dt_control_allow_change_cursor();
          dt_control_change_cursor(cursor);
          dt_control_forbid_change_cursor();
        }
      }
      break;
    }
    default:
      break;
  }
 
  if(!handled) gtk_main_do_event(event);
}
 
static gboolean contextual_help_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  dt_control_change_cursor(GDK_X_CURSOR);
  dt_control_forbid_change_cursor();
  gdk_event_handler_set(_main_do_event_help, NULL, NULL);
  return TRUE;
}
 
static gboolean search_accels_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  GtkWidget *main = dt_gui_main_window();
  dt_accels_search(dt_gui_get_accels(), GTK_WINDOW(main), main);
  return TRUE;
}
 
static gboolean supervisor_callback(GtkAccelGroup *group, GObject *acceleratable, guint keyval, GdkModifierType mods, gpointer user_data)
{
  dt_gui_supervisor_window_show();
  return TRUE;
}
 
void append_help(GtkWidget **menus, GList **lists, const dt_menus_t index)
{
  add_sub_menu_entry(menus, lists, _("Online documentation"), index, NULL, open_doc_callback, NULL, NULL, NULL, 0, 0);
  if(strcmp(DT_BUILD_CHANNEL, "nightly") == 0)
    add_sub_menu_entry(menus, lists, _("Update to the latest nightly build"), index, NULL, update_nightly_callback, NULL, NULL, NULL, 0, 0);
  add_sub_menu_entry(menus, lists, _("Ask a question"), index, NULL, open_search_callback, NULL, NULL, NULL, 0, 0);
  add_sub_menu_entry(menus, lists, _("Join the support chat"), index, NULL, open_chat_callback, NULL, NULL, NULL, 0, 0);
  add_sub_menu_entry(menus, lists, _("Join the support forum"), index, NULL, open_forum_callback, NULL, NULL, NULL, 0, 0);
  add_menu_separator(menus[index]);
  add_sub_menu_entry(menus, lists, _("Open contextual help"), index, NULL, contextual_help_callback, NULL, NULL, NULL, 0, 0);
  add_sub_menu_entry(menus, lists, _("Search actions..."), index, NULL, search_accels_callback, NULL, NULL,
                     NULL, GDK_KEY_p, DT_PRIMARY_MASK);
  add_menu_separator(menus[index]);
  add_sub_menu_entry(menus, lists, _("Event supervisor..."), index, NULL, supervisor_callback, NULL, NULL, NULL, 0, 0);
  add_menu_separator(menus[index]);
  add_sub_menu_entry(menus, lists, _("About"), index, NULL, show_about_dialog, NULL, NULL, NULL, 0, 0);
}