LatexilaBuildView

## LatexilaBuildView LatexilaBuildView — Build view |

## Functions

LatexilaBuildMsg * | latexila_build_msg_new ()
void | latexila_build_msg_free ()
void | latexila_build_msg_reinit ()
void | latexila_build_msg_print ()
LatexilaBuildView * | latexila_build_view_new ()
void | latexila_build_view_clear ()
GtkTreeIter | latexila_build_view_add_main_title ()
GtkTreeIter | latexila_build_view_add_job_title ()
void | latexila_build_view_set_title_state ()
GtkTreeIter | latexila_build_view_append_single_message ()
void | latexila_build_view_append_messages ()
void | latexila_build_view_remove_children ()

## Properties

gboolean | has-details | Read / Write / Construct
gboolean | show-badboxes | Read / Write / Construct
gboolean | show-details | Read / Write / Construct
gboolean | show-warnings | Read / Write / Construct

## Signals

void | jump-to-file | Run Last

## Types and Values

| LatexilaBuildView
struct | LatexilaBuildMsg
enum | LatexilaBuildMsgType
enum | LatexilaBuildState

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkTreeView
                        ╰── LatexilaBuildView

## Implemented Interfaces

LatexilaBuildView implements AtkImplementorIface, GtkBuildable and GtkScrollable.

## Includes

    #include <latexila.h>

## Description

A LatexilaBuildView is a GtkTreeView containing the build messages. The build view is contained in the bottom panel.

## Functions

### latexila_build_msg_new ()

    LatexilaBuildMsg *
    latexila_build_msg_new (void);

Free the return value with `latexila_build_msg_free()` when no longer needed.

[skip]

#### Returns

a newly-allocated LatexilaBuildMsg.

### latexila_build_msg_free ()

    void
    latexila_build_msg_free (LatexilaBuildMsg *build_msg);

Frees the `build_msg` structure.

[skip]

#### Parameters

build_msg | a LatexilaBuildMsg. |

### latexila_build_msg_reinit ()

    void
    latexila_build_msg_reinit (LatexilaBuildMsg *build_msg);

Reinitializes a LatexilaBuildMsg.

#### Parameters

build_msg | a LatexilaBuildMsg. |

### latexila_build_msg_print ()

    void
    latexila_build_msg_print (LatexilaBuildMsg *build_msg);

Prints `build_msg` on stdout, for debugging purposes.

#### Parameters

build_msg | a LatexilaBuildMsg. |

### latexila_build_view_new ()

    LatexilaBuildView *
    latexila_build_view_new (void);

#### Returns

a new LatexilaBuildView.

### latexila_build_view_clear ()

    void
    latexila_build_view_clear (LatexilaBuildView *build_view);

Clears the build view.

#### Parameters

build_view | a LatexilaBuildView. |

### latexila_build_view_add_main_title ()

    GtkTreeIter
    latexila_build_view_add_main_title (LatexilaBuildView *build_view,
                                        const gchar *main_title,
                                        LatexilaBuildState state);

Adds a build tool title. There should be only one main title.

#### Parameters

build_view | a LatexilaBuildView. |
main_title | the title. |
state | the current state of the build tool. |

#### Returns

the title ID as a GtkTreeIter.

### latexila_build_view_add_job_title ()

    GtkTreeIter
    latexila_build_view_add_job_title (LatexilaBuildView *build_view,
                                       const gchar *job_title,
                                       LatexilaBuildState state);

Adds a build job title.

#### Parameters

build_view | a LatexilaBuildView. |
job_title | the title. |
state | the current state of the build job. |

#### Returns

the title ID as a GtkTreeIter.

### latexila_build_view_set_title_state ()

    void
    latexila_build_view_set_title_state (LatexilaBuildView *build_view,
                                         GtkTreeIter *title_id,
                                         LatexilaBuildState state);

Changes the build state of a title, represented as an icon. If `title_id` is the main title, `state` is for the whole build tool. If `title_id` is for a job title, `state` is for the build job.

#### Parameters

build_view | a LatexilaBuildView. |
title_id | the title ID as a GtkTreeIter. |
state | the new state. |

### latexila_build_view_append_single_message ()

    GtkTreeIter
    latexila_build_view_append_single_message
                                   (LatexilaBuildView *build_view,
                                    GtkTreeIter *parent,
                                    LatexilaBuildMsg *message);

Appends a single message to the build view.

#### Parameters

build_view | a LatexilaBuildView. |
parent | the parent row in the tree. |
message | the build message structure. |

#### Returns

the GtkTreeIter where the message has been added.

### latexila_build_view_append_messages ()

    void
    latexila_build_view_append_messages (LatexilaBuildView *build_view,
                                         GtkTreeIter *parent,
                                         const GList *messages,
                                         gboolean expand);

Appends a tree of messages to the build view.

#### Parameters

build_view | a LatexilaBuildView. |
parent | the parent row in the tree. |
messages | the tree of LatexilaBuildMsg's to append. | [element-type LatexilaBuildMsg]
expand | whether to expand the `parent` . |

### latexila_build_view_remove_children ()

    void
    latexila_build_view_remove_children (LatexilaBuildView *build_view,
                                         GtkTreeIter *parent);

Removes the children of `parent` .

#### Parameters

build_view | a LatexilaBuildView. |
parent | the row for which the children must be removed. |

## Types and Values

### LatexilaBuildView

    typedef struct _LatexilaBuildView LatexilaBuildView;

### struct LatexilaBuildMsg

    struct LatexilaBuildMsg {
      LatexilaBuildMsgType type;
      gchar *text;
      gchar *filename;
      gint start_line;
      gint end_line;

      /* There are several reasons to use a GQueue:
       * 1. A GQueue is convenient for appending at the end of the list.
       * 2. An external GNode containing the build messages is not convenient for
       * running sub-post-processors, for example the latex post-processor inside
       * latexmk. A GNode has a reference to its parent, so it's more difficult to
       * embed the messages of a sub-post-processor. Moreover, we don't need to know
       * the parent, a GNode uses useless memory. A GSList would use even less
       * memory, but it's less convenient to use.
       */
      GQueue *children;

      guint expand : 1;
    };

A build message, one line in the GtkTreeView. If a `filename` is provided, the file will be opened when the user clicks on the message. If `start_line` and `end_line` are provided, the lines between the two positions will be selected.

#### Members

LatexilaBuildMsgType `type`; | the message type. |
gchar *`text`; | the text. |
gchar *`filename`; | reference to a certain file. |
gint `start_line`; | reference to a line in the file. -1 to unset. |
gint `end_line`; | reference to a line in the file. -1 to unset. |
GQueue *`children`; | list of children of type LatexilaBuildMsg. |
guint `expand` : 1; | if the message has children, whether to initially show them. |

### enum LatexilaBuildMsgType

#### Members

LATEXILA_BUILD_MSG_TYPE_MAIN_TITLE | main title. |
LATEXILA_BUILD_MSG_TYPE_JOB_TITLE | build job title. |
LATEXILA_BUILD_MSG_TYPE_JOB_SUB_COMMAND | build job sub-command. |
LATEXILA_BUILD_MSG_TYPE_ERROR | error. |
LATEXILA_BUILD_MSG_TYPE_WARNING | warning. |
LATEXILA_BUILD_MSG_TYPE_BADBOX | badbox. |
LATEXILA_BUILD_MSG_TYPE_INFO | other info. |

### enum LatexilaBuildState

#### Members

LATEXILA_BUILD_STATE_RUNNING | running. |
LATEXILA_BUILD_STATE_SUCCEEDED | succeeded. |
LATEXILA_BUILD_STATE_FAILED | failed. |
LATEXILA_BUILD_STATE_ABORTED | aborted. |

## Property Details

### The `“has-details”` property

      “has-details”              gboolean

Flags: Read / Write / Construct

Default value: FALSE

### The `“show-badboxes”` property

      “show-badboxes”            gboolean

Flags: Read / Write / Construct

Default value: TRUE

### The `“show-details”` property

      “show-details”             gboolean

Flags: Read / Write / Construct

Default value: FALSE

### The `“show-warnings”` property

      “show-warnings”            gboolean

Flags: Read / Write / Construct

Default value: TRUE

## Signal Details

### The `“jump-to-file”` signal

    void
    user_function (LatexilaBuildView *build_view,
                   GFile             *file,
                   gint               start_line,
                   gint               end_line,
                   gpointer           user_data)

The ::jump-to-file signal is emitted when a row in the build view is selected. The row must contain a file, otherwise the signal is not emitted. The file should be opened and presented to the user. If `start_line` and `end_line` are not -1, jump to the `start_line` and select those lines. If `start_line` is provided, `end_line` is also provided (different than -1).

#### Parameters

build_view | a LatexilaBuildView. |
file | the file to open. |
start_line | the line where to jump and the start of the selection, or -1. |
end_line | the end of the selection, or -1. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last