GtexBuildView: Enter TeX Reference Manual

## GtexBuildView GtexBuildView — Build view |

## Functions

GtexBuildMsg * | gtex_build_msg_new ()
void | gtex_build_msg_free ()
void | gtex_build_msg_reinit ()
void | gtex_build_msg_print ()
GtexBuildView * | gtex_build_view_new ()
void | gtex_build_view_clear ()
GtkTreeIter | gtex_build_view_add_main_title ()
GtkTreeIter | gtex_build_view_add_job_title ()
void | gtex_build_view_set_title_state ()
GtkTreeIter | gtex_build_view_append_single_message ()
void | gtex_build_view_append_messages ()
void | gtex_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

struct | GtexBuildView
struct | GtexBuildMsg
enum | GtexBuildMsgType
enum | GtexBuildState

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkTreeView
                        ╰── GtexBuildView

## Implemented Interfaces

GtexBuildView implements AtkImplementorIface, GtkBuildable and GtkScrollable.

## Includes

    #include <gtex.h>

## Description

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

## Functions

### gtex_build_msg_new ()

    GtexBuildMsg *
    gtex_build_msg_new (void);

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

[skip]

#### Returns

a newly-allocated GtexBuildMsg.

### gtex_build_msg_free ()

    void
    gtex_build_msg_free (GtexBuildMsg *build_msg);

Frees the `build_msg` structure.

[skip]

#### Parameters

build_msg | a GtexBuildMsg. |

### gtex_build_msg_reinit ()

    void
    gtex_build_msg_reinit (GtexBuildMsg *build_msg);

Reinitializes a GtexBuildMsg.

#### Parameters

build_msg | a GtexBuildMsg. |

### gtex_build_msg_print ()

    void
    gtex_build_msg_print (GtexBuildMsg *build_msg);

Prints `build_msg` on stdout, for debugging purposes.

#### Parameters

build_msg | a GtexBuildMsg. |

### gtex_build_view_new ()

    GtexBuildView *
    gtex_build_view_new (void);

#### Returns

a new GtexBuildView.

### gtex_build_view_clear ()

    void
    gtex_build_view_clear (GtexBuildView *build_view);

Clears the build view.

#### Parameters

build_view | a GtexBuildView. |

### gtex_build_view_add_main_title ()

    GtkTreeIter
    gtex_build_view_add_main_title (GtexBuildView *build_view,
                                    const gchar *main_title,
                                    GtexBuildState state);

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

#### Parameters

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

#### Returns

the title ID as a GtkTreeIter.

### gtex_build_view_add_job_title ()

    GtkTreeIter
    gtex_build_view_add_job_title (GtexBuildView *build_view,
                                   const gchar *job_title,
                                   GtexBuildState state);

Adds a build job title.

#### Parameters

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

#### Returns

the title ID as a GtkTreeIter.

### gtex_build_view_set_title_state ()

    void
    gtex_build_view_set_title_state (GtexBuildView *build_view,
                                     GtkTreeIter *title_id,
                                     GtexBuildState 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 GtexBuildView. |
title_id | the title ID as a GtkTreeIter. |
state | the new state. |

### gtex_build_view_append_single_message ()

    GtkTreeIter
    gtex_build_view_append_single_message (GtexBuildView *build_view,
                                           GtkTreeIter *parent,
                                           GtexBuildMsg *message);

Appends a single message to the build view.

#### Parameters

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

#### Returns

the GtkTreeIter where the message has been added.

### gtex_build_view_append_messages ()

    void
    gtex_build_view_append_messages (GtexBuildView *build_view,
                                     GtkTreeIter *parent,
                                     const GList *messages,
                                     gboolean expand);

Appends a tree of messages to the build view.

#### Parameters

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

### gtex_build_view_remove_children ()

    void
    gtex_build_view_remove_children (GtexBuildView *build_view,
                                     GtkTreeIter *parent);

Removes the children of `parent` .

#### Parameters

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

## Types and Values

### struct GtexBuildView

    struct GtexBuildView;

### struct GtexBuildMsg

    struct GtexBuildMsg {
    	GtexBuildMsgType 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 (the selection stops at the end of `end_line` ).

#### Members

GtexBuildMsgType `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, counting from 1. -1 to unset. |
gint `end_line`; | reference to a line in the file, counting from 1. -1 to unset. |
GQueue *`children`; | list of children of type GtexBuildMsg. |
guint `expand` : 1; | if the message has children, whether to initially show them. |

### enum GtexBuildMsgType

#### Members

GTEX_BUILD_MSG_TYPE_MAIN_TITLE | main title. |
GTEX_BUILD_MSG_TYPE_JOB_TITLE | build job title. |
GTEX_BUILD_MSG_TYPE_JOB_SUB_COMMAND | build job sub-command. |
GTEX_BUILD_MSG_TYPE_ERROR | error. |
GTEX_BUILD_MSG_TYPE_WARNING | warning. |
GTEX_BUILD_MSG_TYPE_BADBOX | badbox. |
GTEX_BUILD_MSG_TYPE_INFO | other info. |

### enum GtexBuildState

#### Members

GTEX_BUILD_STATE_RUNNING | running. |
GTEX_BUILD_STATE_SUCCEEDED | succeeded. |
GTEX_BUILD_STATE_FAILED | failed. |
GTEX_BUILD_STATE_ABORTED | aborted. |

## Property Details

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

      “has-details”              gboolean

Owner: GtexBuildView

Flags: Read / Write / Construct

Default value: FALSE

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

      “show-badboxes”            gboolean

Owner: GtexBuildView

Flags: Read / Write / Construct

Default value: TRUE

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

      “show-details”             gboolean

Owner: GtexBuildView

Flags: Read / Write / Construct

Default value: FALSE

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

      “show-warnings”            gboolean

Owner: GtexBuildView

Flags: Read / Write / Construct

Default value: TRUE

## Signal Details

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

    void
    user_function (GtexBuildView *build_view,
                   GFile         *file,
                   int            start_line,
                   int            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).

The selection should stop at the end of `end_line` (not at the start of `end_line` ).

#### Parameters

build_view | a GtexBuildView. |
file | the file to open. |
start_line | the start of the selection, counting from 0. Or -1 if unset. |
end_line | the end of the selection, counting from 0. Or -1 if unset. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last