## 1. Project Overview & Quickstart (mono/CONTRIBUTING) # CONTRIBUTING Open-source repository mono/CONTRIBUTING ### Repository Details - **Repository:** [mono/CONTRIBUTING](https://github.com/mono/CONTRIBUTING) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (mono/website) ## File: README.md Mono Project Website ======================================================================================== This repository contains the files used for generating the [Mono website](http://www.mono-project.com). The site uses [Jekyll](http://jekyllrb.com), a static site generator. GitHub Pages, where the site is hosted, natively supports Jekyll so every time someone pushes to this repository, the website will be built and updated. For hosting it yourself, see [Setting up a local copy of the website](#setting-up-a-local-copy-of-the-website). Contributing to the website --------------------------- **Note:** Major issues or feature requests should be filed on the [issue tracker](https://github.com/mono/website/issues) first, so we can discuss the implications. If you want to edit a page, the easiest way is to click the link under the page title on the website. This will open the source file on GitHub where you can click the pencil button to start editing: GitHub's editor shows you both the [Markdown](https://guides.github.com/features/mastering-markdown/) source as well as a preview of the rendered page: After you've finished your changes, enter a proper summary and description and click the "Propose file change" button to open a pull request: Setting up a local copy of the website -------------------------------------- For larger changes, using the web-based editor on GitHub is not really convenient. A better way is to setup a local copy of the website where you can experiment. ### Dependencies - [Ruby](https://www.ruby-lang.org/) - Jekyll is written in Ruby - [Bundler](http://bundler.io/) - a package manager for Ruby. Install it by running `gem install bundler` After you've forked and cloned the repository, run the following commands: 1. `bundle install` - downloads the required libraries 2. `bundle exec jekyll serve` - builds the website and runs a local webserver on port 4000 **Note:** you can add the `--watch` option when running `jekyll serve` to let Jekyll watch for file changes, which means the site will be rebuilt when a file is modified. **Note 2:** on case-insensitive file systems like on Windows and macOS you'll run into redirect loops for some URLs. The workaround is to disable redirects locally by removing the `plugins: jekyll-redirect-from` entry from `_config.yml`. The site should now be running locally: Repository structure -------------------- - `_includes` - *special folder* contains snippets that can be included via `{% include file.html %}` in other pages - `_layouts` - *special folder* contains the layouts that are shared between pages. Layouts can be inherited, the root layout is `base.html`. - `_posts` - *special folder*, contains the source pages for the blog section, see [Writing a blog post](#writing-a-blog-post) - `_site` - the output of the generated site is stored here by default, this folder only exists after Jekyll built the site - `archived` - content that is no longer relevant but kept to keep external links working - `community` - contains the source pages for the `/community` website section - `css` - contains the main stylesheet - `docs` - contains the source pages for the `/docs` website section - `download` - contains the source pages for the `/download` website section - `files` - stores binary files used in pages - `images` - stores the images used in pages - `news` - lists the blog pages from the `_posts` directory Writing a blog post ------------------- Blogging is very easy with Jekyll. Browse to `_posts` directory, copy the Markdown file `_TEMPLATE.md` and rename that file following the file name convention: `YEAR-MONTH-DAY-title.md`. Then open the file you renamed and follow the steps there to complete writing a blog post. Make sure to not include special characters in the file name. The blog entry's publishing date is automatically extracted from the file name. --- ## File: docs/gui/gtksharp/widgets/adjustments.md --- title: "GtkSharp: Adjustments" redirect_from: - /GtkSharp%3A_Adjustments/ --- Gtk# has various widgets that can be visually adjusted by the user using the mouse or the keyboard, such as the range widgets, described in the Range Widgets section. There are also a few widgets that display some adjustable portion of a larger area of data, such as the text widget and the viewport widget. Obviously, an application needs to be able to react to changes the user makes in range widgets. One way to do this would be to have each widget emit its own type of signal when its adjustment changes, and either pass the new value to the signal handler, or require it to look inside the widget's data structure in order to ascertain the value. But you may also want to connect the adjustments of several widgets together, so that adjusting one adjusts the others. The most obvious example of this is connecting a scrollbar to a panning viewport or a scrolling text area. If each widget has its own way of setting or getting the adjustment value, then the programmer may have to write their own signal handlers to translate between the output of one widget's signal and the "input" of another's adjustment setting function. Gtk# solves this problem using the Adjustment object, which is not a widget but a way for widgets to store and pass adjustment information in an abstract and flexible form. The most obvious use of Adjustment is to store the configuration parameters and values of range widgets, such as scrollbars and scale controls. However, since Adjustments are derived from Object, they have some special powers beyond those of normal data structures. Most importantly, they can emit signals, just like widgets, and these signals can be used not only to allow your program to react to user input on adjustable widgets, but also to propagate adjustment values transparently between adjustable widgets. You will see how adjustments fit in when you see the other widgets that incorporate them: Progress Bars, Viewports, Scrolled Windows, and others. ## Creating Adjustments Many of the widgets which use adjustment objects do so automatically, but some cases will be shown in later examples where you may need to create one yourself. You create an adjustment using: ``` csharp Gtk.Object adjustment = new Adjustment( double value, double lower, double upper, double stepIncrement, double pageIncrement, double pageSize ); ``` The value argument is the initial value you want to give to the adjustment, usually corresponding to the topmost or leftmost position of an adjustable widget. The lower argument specifies the lowest value which the adjustment can hold. The stepIncrement argument specifies the "smaller" of the two increments by which the user can change the value, while the pageIncrement is the "larger" one. The pageSize argument usually corresponds somehow to the visible area of a panning widget. The upper argument is used to represent the bottom most or right most coordinate in a panning widget's child. Therefore it is not always the largest number that value can take, since the pageSize of such widgets is usually non-zero. ## Using Adjustments The adjustable widgets can be roughly divided into those which use and require specific units for these values and those which treat them as arbitrary numbers. ### Specific Unit Adjustments The other group which treats the values as specific units includes the text widget, the viewport widget, the compound list widget, and the scrolled window widget. All of these widgets use pixel values for their adjustments. These are also all widgets which are typically "adjusted" indirectly using scrollbars. While all widgets which use adjustments can either create their own adjustments or use ones you supply, you'll generally want to let this particular category of widgets create its own adjustments. Usually, they will eventually override all the values except the value itself in whatever adjustments you give them, but the results are, in general, undefined (meaning, you'll have to read the source code to find out, and it may be different from widget to widget). Now, you're probably thinking, since text widgets and viewports insist on setting everything except the value of their adjustments, while scrollbars will only touch the adjustment's value, if you share an adjustment object between a scrollbar and a text widget, manipulating the scrollbar will automagically adjust the viewport widget? Of course it will! Just like this: ``` csharp /* creates its own adjustments */ Viewport viewport = new Viewport(null, null); /* uses the newly-created adjustment for the scrollbar as well */ VScrollbar vscrollbar = new VScrollbar(viewport.Adjustment); ``` ### Arbitrary Number Adjustments The other group includes the range widgets (scrollbars and scales, the progress bar widget, and the spin button widget). These widgets are all the widgets which are typically "adjusted" directly by the user with the mouse or keyboard. They will treat the lower and upper values of an adjustment as a range within which the user can manipulate the adjustment's value. By default, they will only modify the value of an adjustment. --- ## File: docs/gui/gtksharp/widgets/arrows.md --- title: "GtkSharp: Arrows" redirect_from: - /GtkSharp%3A_Arrows/ --- The Arrow widget draws an arrowhead, facing in a number of possible directions and having a number of possible styles. It can be very useful when placed on a button in many applications. Like the Label widget, it emits no signals. [Image:arrows.png] There are only two functions for manipulating an Arrow widget: ``` csharp Arrow arrow1 = new Arrow( arrow_type, shadow_type ); arrow1.SetArrow(arrow_type, shadow_type ); ``` The first creates a new arrow widget with the indicated type and appearance. The second allows these values to be altered. The arrow_type argument may take one of the following values: Gtk.Arrow.Up Gtk.Arrow.Down Gtk.Arrow.Left Gtk.Arrow.Right These values obviously indicate the direction in which the arrow will point. The shadow_type argument may take one of these values: Gtk.Shadow.In Gtk.Shadow.Out (the default) Gtk.Shadow.Etched.In Gtk.Shadow.Etched.Out Here's a brief example to illustrate their use. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ## File: docs/gui/gtksharp/widgets/buttons.md --- title: "GtkSharp: Buttons" redirect_from: - /GtkSharp%3A_Buttons/ - /GtkSharp%3A_Normal_Buttons/ --- ## Normal Buttons There are two ways to create normal [buttons](http://docs.go-mono.com/index.aspx?link=T:Gtk.Button): ``` csharp Button button1 = new Button("labeltext"); ``` or ``` csharp Button button1 = Button.NewWithMnemonic("Hello World"); ``` After creating a button using its argument-less constructor, it's then up to you to pack a label or pixmap into this new button. To do this, create a new box, and then pack your objects into this box using the usual [Gtk.Box.PackStart](http://docs.go-mono.com/index.aspx?link=M:Gtk.Box.PackStart), and then use [Gtk.Container.Add](http://docs.go-mono.com/index.aspx?link=M:Gtk.Container.Add) to pack the button into the box. Here's an example of creating a button with a image and a label in it. I've broken up the code to create a box from the rest so you can use it in your programs. There are further examples of using images later in the tutorial. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Toggle Buttons ToggleButtons are similiar to normal buttons, but they keep track of their state--- up or down. When you click on one, it will be pushed down, and when you click again, it will pop back up. Click again, and it will pop back down. When popped down, the button's Active property has the value "true". Toggle buttons are the basis for check buttons and radio buttons; as such, many of the calls used for toggle buttons are inherited by radio and check buttons. ``` csharp using Gtk; using System; using System.Drawing;   public class togglebuttons {     public static void Main(string[] args) {   Application.Init();     Window window = new Window("toggle buttons");   window.DeleteEvent += delete_event;   /* Creating a new ToggleButton*/   ToggleButton togglebutton = new ToggleButton ("button1"); togglebutton.Clicked += clickedCallback;     window.Add(togglebutton); window.ShowAll();   Application.Run();   }   static void delete_event (object obj, DeleteEventArgs args) {   Application.Quit(); }   static void clickedCallback (object obj, EventArgs args) { /* Check Active Property */   if (((ToggleButton) obj).Active) Console.WriteLine ("ToggleButton clicked, I'm activating"); } } ``` ## Check Buttons Check buttons inherit many properties and functions from the the toggle buttons above, but look a little different. Rather than being buttons with text inside them, they are small squares with the text to the right of them. These are often used for toggling options on and off in applications. The creation functions are similar to those of the normal button. ``` csharp GtkWidget CheckButton1 = new CheckButton(); GtkWidget CheckButton1 = new CheckButtonWithLabel(string label); GtkWidget CheckButton1 = new CheckButtonWithMnemonic(string label); ``` The CheckButtonWithLabel() function creates a check button with a label beside it. Checking the state of the check button is identical to that of the toggle button. ## Radio Buttons ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ## File: docs/gui/gtksharp/widgets/dialogs.md --- title: "GtkSharp: Dialogs" redirect_from: - /GtkSharp%3A_Dialogs/ --- Warning: Gnome.Dialog has not been implemented. This part of the wiki is alone for reference when the widget Dialog this borne in Monkey this documentation to be brought up to date The Dialog widget is quite simple, but very useful, commonly is used to unfold windows pop-up or similar tasks to this where is desired to unfold information specifies and to obtain an interaction on the part of the user. To se of the Dialog widget we can make use of some of the two constructors that are shown subsequently: ``` csharp public Dialog (System.IntPtr raw) ``` ``` csharp public Dialog (string title, string buttons) ``` --- ## File: docs/gui/gtksharp/widgets/fixed-container.md --- title: "GtkSharp: Fixed Container" redirect_from: - /GtkSharp%3A_Fixed_Container/ --- The Fixed container allows you to place widgets at a fixed position within it's window, relative to it's upper left hand corner. The position of the widgets can be changed dynamically. There are only a few functions associated with the fixed widget: Fixed fixed1 = new Fixed(); fixed1.Put(widget, x, y); fixed1.Move(widget, x, y); Put() places a widget in the container fixed at the position specified by x and y. Move() allows the specified widget to be moved to a new position. Normally, Fixed widgets don't have their own X window. Since this is different from the behaviour of Fixed widgets in earlier releases of GTK, the property HasWindow allows the creation of Fixed widgets with their own window. It has to be called before realizing the widget. --- ## File: docs/gui/gtksharp/widgets/frames.md --- title: "GtkSharp: Frames" redirect_from: - /GtkSharp%3A_Frames/ --- Frames can be used to enclose one or a group of widgets with a box which can optionally be labeled. The position of the label and the style of the box can be altered to suit. A Frame can be created with the following constructor: Frame frame1 = new Frame("Label"); The label is by default placed in the upper left hand corner of the frame. A value of null for the label argument will result in no label being displayed. The text of the label can be changed using the Label property. The position of the label can be changed using the SetLabelAlign method: frame1.SetLabelAlign(xalign, yalign); xalign and yalign take values between 0.0 and 1.0. xalign indicates the position of the label along the top horizontal of the frame. yalign is not currently used. The default value of xalign is 0.0 which places the label at the left hand end of the frame. The ShadowType property alters the style of the box that is used to outline the frame. It can take one of the following values: Gtk.Shadow.None, Gtk.Shadow.In, Gtk.Shadow.Out, Gtk.Shadow.EtchedIn (default), or Gtk.Shadow.EtchedOut. The following code example illustrates the use of the Frame widget. [Image:frame.png] ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ## File: docs/gui/gtksharp/widgets/index.md --- title: "GtkSharp: Widget Overview" --- Overview of the Widgets used in GTK# ------------------------------------ - [Widget Hierarchy](/docs/gui/gtksharp/widgets/widget-hierarchy/) - [The Button Widget](/docs/gui/gtksharp/widgets/buttons/) - [Labels](/docs/gui/gtksharp/widgets/labels/) - [Arrows](/docs/gui/gtksharp/widgets/arrows/) - [Tooltips](/docs/gui/gtksharp/widgets/tooltips/) - [Progress Bars](/docs/gui/gtksharp/widgets/progress-bars/) - [Adjustments](/docs/gui/gtksharp/widgets/adjustments/) - [Range Widgets](/docs/gui/gtksharp/widgets/range-widgets/) - [Scrollbar Widgets](/docs/gui/gtksharp/widgets/scrollbar-widgets/) - [Scale Widgets](/docs/gui/gtksharp/widgets/scale-widgets/) - [Dialogs](/docs/gui/gtksharp/widgets/dialogs/) - Menu Widget Example (unwritten) - [Widget Colours](/docs/gui/gtksharp/widgets/widget-colours/) Widgets without Windows ----------------------- The following widgets do not have an associated window. If you want to capture events, you'll have to use the EventBox. For more information, see the section on the EventBox widget. Gtk.Alignment Gtk.Arrow Gtk.Bin Gtk.Box Gtk.Button Gtk.CheckButton Gtk.Fixed Gtk.Image Gtk.Label Gtk.MenuItem Gtk.Notebook Gtk.Paned Gtk.RadioButton Gtk.Range Gtk.ScrolledWindow Gtk.Separator Gtk.Table Gtk.Toolbar Gtk.AspectFrame Gtk.Frame Gtk.VBox Gtk.HBox Gtk.VSeparator Gtk.HSeparator --- ## File: docs/gui/gtksharp/widgets/labels.md --- title: "GtkSharp: Labels" redirect_from: - /GtkSharp%3A_Labels/ --- Labels are used a lot in Gtk#, and are relatively simple. Labels emit no events as they do not have an associated X window. If you need to catch events, or do clipping, place it inside an EventBox widget or a Button widget. [Image:labels.png] To create a new label, use: ``` csharp Label label1 = new Label(text); ``` The sole argument is the string you wish the label to display. To change the label's text after creation, use its Text property. The space needed for the new string will be automatically adjusted if needed. You can produce multi-line labels by putting line breaks in the label string and setting the LineWrap property to true. The label text can be aligned/justified using the Justify property, which takes a Gtk.Justify enumeration value: Left, Right, Center, or Fill. If you want your label underlined, then you can set a pattern on the label: ``` csharp label1.Pattern = pattern; ``` The pattern argument indicates how the underlining should look. It consists of a string of underscore and space characters. An underscore indicates that the corresponding character in the label should be underlined. For example, the string "`__     __`" would underline the first two characters and eight and ninth characters. If you simply want to have an underlined accelerator ("mnemonic") in your label, you should create the Label with LabelWithMnemonic() or use the TextWithMnemonic property, not the Pattern property. Below is a short example to illustrate these functions. This example makes use of the Frame widget to better demonstrate the label styles. You can ignore this for now as the Frame widget is explained later on. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ## File: docs/gui/gtksharp/widgets/layout-container.md --- title: "GtkSharp: Layout Container" redirect_from: - /GtkSharp%3A_Layout_Container/ --- The Layout container is similar to the Fixed container except that it implements an infinite (where infinity is less than 2\^32) scrolling area. The X window system has a limitation where windows can be at most 32767 pixels wide or tall. The Layout container gets around this limitation by doing some exotic stuff using window and bit gravities, so that you can have smooth scrolling even when you have many child widgets in your scrolling area. A Layout container is created using: Layout layout1 = new Layout(hadjustment, vadjustment); As you can see, you can optionally specify the Adjustment objects that the Layout widget will use for its scrolling. You can add and move widgets in the Layout container using the following two functions: layout1.Put(widget, x, y); layout1.Move(widget, x, y); The size of the Layout container can be set using the next function: layout1.Size = new Size(width, height );