1/**************************************************************************** 2** 3** Copyright (C) 2020 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the Qt Creator documentation. 7** 8** Commercial License Usage 9** Licensees holding valid commercial Qt licenses may use this file in 10** accordance with the commercial license agreement provided with the 11** Software or, alternatively, in accordance with the terms contained in 12** a written agreement between you and The Qt Company. For licensing terms 13** and conditions see https://www.qt.io/terms-conditions. For further 14** information use the contact form at https://www.qt.io/contact-us. 15** 16** GNU Free Documentation License Usage 17** Alternatively, this file may be used under the terms of the GNU Free 18** Documentation License version 1.3 as published by the Free Software 19** Foundation and appearing in the file included in the packaging of 20** this file. Please review the following information to ensure 21** the GNU Free Documentation License version 1.3 requirements 22** will be met: https://www.gnu.org/licenses/fdl-1.3.html. 23** 24****************************************************************************/ 25 26/*! 27//! [json wizards] 28 \section1 Integrating Wizards into Builds 29 30 To integrate the wizard into \QC and to deliver it as part of the \QC build, 31 place the wizard files in the \QC sources. Then select \uicontrol Build > 32 \uicontrol {Run qmake}, so that the new files you added for your wizard are 33 actually copied from the \QC source directory into the \QC build directory 34 as part of the next \QC build. 35 36 If you do not run qmake, your new wizard will not show up, because it does 37 not exist in the build directory you run your newly built \QC from. It never 38 got copied there, because make did not know that the files exist in the 39 source tree, because qmake did not inform make that the files were added 40 recently. 41 42 Basically, qmake generates a fixed list of files to copy from the source 43 directory to the sudirectory of the build directory that is checked for 44 wizards at runtime. Therefore, you need to run qmake or execute the 45 \uicontrol {Factory.Reset} function each time the names or locations of the 46 files change. 47 48 \section1 Using Variables in Wizards 49 50 You can use variables (\c {%\{<variableName>\}}) in strings in the JSON configuration 51 file and in template source files. 52 A set of variables is predefined by the wizards and their pages. 53 You can introduce new variables as shortcuts to be used later by 54 defining the variable key names and values in the \c options section in the 55 \c {wizard.json} file. 56 57 There is a special variable \c {%\{JS:<JavaScript expression>\}} which evaluates the given 58 JavaScript expression and converts the resulting JavaScript value to a string. 59 In the JavaScript expression you can refer to variables defined by the wizard with 60 \c {value('<variableName>')}. The returned JavaScript object has the type that the value 61 of the variable has, which can be a string, list, dictionary or boolean. 62 63 In places where a boolean value is expected and a string is given, 64 an empty string as well as the string \c {"false"} is treated as 65 \c false and anything else as \c true. 66 67 \section1 Localizing Wizards 68 69 If a setting name starts with the \c tr prefix, the value is visible to 70 users and should be translated. If the new wizard is included in the \QC 71 sources, the translatable strings appear in the \QC translation files and 72 can be translated as a part of \QC. Alternatively, you can place the 73 translations in the .json file using the following syntax: 74 75 \code 76 "trDisplayName": { "C": "default", "en_US": "english", "de_DE": "deutsch" } 77 \endcode 78 79 For example: 80 81 \code 82 "trDisplayName": { "C": "Project Location", "en_US": "Project Location", "de_DE": "Projekt Verzeichnis" } 83 \endcode 84 85 \section1 Creating Wizards 86 87 \QC contains wizards for adding classes, files, and projects. You can 88 use them as basis for adding your own wizards. We use the C++ wizard 89 to explain the process and the sections and settings in the .json file. 90 91 In this example, we create the wizard directory in the shared directory 92 and integrate it in the \QC build system, so that it can deployed along with 93 the \QC binaries as part of the build. 94 95 \image qtcreator-cpp-class-wizard.png 96 97 For more information about the pages and widgets that you can add and their 98 supported properties, see \l {Available Pages} and \l{Available Widgets}. 99 100 To create a JSON-based C++ class wizard: 101 102 \list 1 103 104 \li Start \QC with the \c {-customwizard-verbose} argument to receive 105 feedback during wizard development. For more information, see 106 \l {Verbose Output}. 107 108 \li Set keyboard shortcuts for the \uicontrol Inspect and 109 \uicontrol {Factory.Reset} actions, as described in 110 \l {Tips for Wizard Development}. 111 112 \li Make a copy of \c {share/qtcreator/templates/wizards/classes/cpp} 113 and rename it. For example, 114 \c {share/qtcreator/templates/wizards/classes/mycpp} 115 116 \li Use the \uicontrol {Factory.Reset} action to make the wizard appear 117 in \uicontrol File > \uicontrol {New File or Project} without 118 restarting \QC. 119 120 \li Open the wizard configuration file, \c {wizard.json} for editing: 121 122 \list 123 124 \li The following settings determine the type of the wizard and 125 its place in the \uicontrol {New File or Project} dialog: 126 127 \code 128 "version": 1, 129 "supportedProjectTypes": [ ], 130 "id": "A.Class", 131 "category": "O.C++", 132 \endcode 133 134 \list 135 136 \li \c version is the version of the file contents. Do not 137 modify this value. 138 139 \li \c supportedProjectTypes is an optional setting that 140 can be used to filter wizards when adding a new build 141 target to an existing project. For example, only wizards 142 that produce qmake projects should be provided when 143 adding a new target to an existing qmake project. 144 145 Possible values are the build systems supported by \QC 146 or \c UNKNOWN_PROJECT if the build system is not 147 specified: \c AutotoolsProjectManager.AutotoolsProject, 148 \c CMakeProjectManager.CMakeProject, 149 \c GenericProjectManager.GenericProject, 150 \c PythonProject, \c Qbs.QbsProject, 151 \c Qt4ProjectManager.Qt4Project (qmake project), 152 \c QmlProjectManager.QmlProject 153 154 \li \c id is the unique identifier for your wizard. Wizards 155 are sorted by the ID in alphabetic order within the 156 \c category. You can use a leading letter to specify the 157 position of the wizard. You must always change 158 this value. For example, \c B.MyClass. 159 160 This information is available in the wizard as 161 \c {%\{id\}}. 162 163 \li \c category is the category in which to place the wizard 164 in the list. You can use a leading letter to specify the 165 position of the category in the list in the 166 \uicontrol {New File or Project} dialog. 167 168 This information is available in the wizard as 169 \c {%\{category\}}. 170 \endlist 171 172 \li The following settings specify the icon and text that appear in 173 the \uicontrol {New File or Project} dialog: 174 175 \code 176 "trDescription": "Creates a C++ header and a source file for a new class that you can add to a C++ project.", 177 "trDisplayName": "C++ Class", 178 "trDisplayCategory": "C++", 179 "icon": "../../global/genericfilewizard.png", 180 "enabled": "%{JS: value('Plugins').indexOf('CppEditor') >= 0}", 181 \endcode 182 183 \list 184 185 \li \c trDescription appears in the right-most panel when 186 \c trDisplayCategory is selected. 187 188 This information is available in the wizard as 189 \c {%\{trDescription\}}. 190 191 \li \c trDisplayName appears in the middle panel when 192 \c trDisplayCategory is selected. 193 194 This information is available in the wizard as 195 \c {%\{trDisplayName\}}. 196 197 \li \c trDisplayCategory appears in the 198 \uicontrol {New File or Project} dialog, under 199 \uicontrol Projects. 200 201 This information is available in the wizard as 202 \c {%\{trDisplayCategory\}}. 203 204 \li \c icon appears next to the \c trDisplayName in the middle 205 panel when \c trDisplayCategory is selected. We recommend 206 that you specify the path relative to the wizard.json file, 207 but you can also use an absolute path. 208 209 \li \c image specifies a path to an image (for example a 210 screenshot) that appears below the \c trDescription. 211 212 \li \c featuresRequired specifies the \QC features that the 213 wizard depends on. If a required feature is missing, the 214 wizard is hidden. For example, if no kit has a Qt version 215 set, then the qmake-based wizards are hidden. 216 217 Use \c enabled if you need to express more complex logic to 218 decide whether or not your wizard will be available. 219 220 This information is available in the wizard as 221 \c {%\{RequiredFeatures\}}. 222 223 \li \c featuresPreferred specifies the build and run kits to 224 preselect. 225 226 This information is available in the wizard as 227 \c {%\{PreferredFeatures\}}. 228 229 \li \c platformIndependent is set to \c true if the wizard is 230 supported by all target platforms. By default, it is set to 231 \c{false}. 232 233 \li \c enabled is evaluated to determine whether a wizard is 234 listed in \uicontrol Files > 235 \uicontrol {New File or Project}, after \c featuresRequired 236 has been checked. 237 238 The default value is \c true. 239 240 \endlist 241 242 \li The \c options section contains an array of objects with \e key 243 and \e value attributes. You can define your own variables to 244 use in the configuration and template source files, in addition 245 to the predefined variables. For example, the following 246 variables are used in the C++ class creation wizard: 247 248 \code 249 "options": 250 [ 251 { "key": "TargetPath", "value": "%{Path}" }, 252 { "key": "HdrPath", "value": "%{Path}/%{HdrFileName}" }, 253 { "key": "SrcPath", "value": "%{Path}/%{SrcFileName}" }, 254 { "key": "CN", "value": "%{JS: Cpp.className(value('Class'))}" }, 255 { "key": "Base", "value": "%{JS: value('BaseCB') === '' ? value('BaseEdit') : value('BaseCB')}" }, 256 { "key": "isQObject", "value": "%{JS: (value('Base') === 'QObject' || value('Base') === 'QWidget' || value('Base') === 'QMainWindow' || value('Base') === 'QDeclarativeItem' || value('Base') === 'QQuickItem' ) ? 'true' : 'false'}" }, 257 { "key": "GUARD", "value": "%{JS: Cpp.classToHeaderGuard(value('Class'), Util.suffix(value('HdrFileName'))}" }, 258 { "key": "SharedDataInit", "value": "%{JS: value('IncludeQSharedData') ? 'data(new %{CN}Data)' : '' }" } 259 ], 260 \endcode 261 262 This section is optional. For more examples of variables, see 263 the \c {wizard.json} files for other wizards. 264 265 \li The \c pages section specifies the wizard pages. The pages 266 used depend on the wizard type. You can add standard pages to 267 wizards or create new pages using the available widgets. The 268 following settings specify the display name, title, and type of 269 the page: 270 271 \code 272 "pages": 273 [ 274 { 275 "trDisplayName": "Define Class", 276 "trShortTitle": "Details", 277 "typeId": "Fields", 278 "data" : 279 [ 280 { 281 "name": "Class", 282 "trDisplayName": "Class name:", 283 "mandatory": true, 284 "type": "LineEdit", 285 "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" } 286 }, 287 ... 288 ] 289 \endcode 290 291 \list 292 293 \li \c typeId specifies the page to use: \c Fields, \c File, 294 \c Form, \c Kits, \c Project, \c VcsConfiguration, 295 \c VcsCommand or \c Summary. 296 297 Full page ID, as used in the code, consists of the 298 \c typeId prefixed with \c {"PE.Wizard.Page."}. For more 299 information, about the pages, see \l{Available Pages}. 300 301 \li \c trDisplayName specifies the title of the page. By 302 default, the page title is used. 303 304 \li \c trShortTitle specifies the title used in the sidebar 305 of the Wizard. By default, the page title is used. 306 307 \li \c trSubTitle specifies the subtitle of the page. By 308 default, the page title is used. 309 310 \li \c index is an integer value that specifies the page ID. 311 It is automatically assigned if you do not set it. 312 313 \li \c enabled is set to \c true to show the page and to 314 \c false to hide it. 315 316 \li \c data specifies the wizard pages. In the C++ wizard, 317 it specifies a \c Fields page and a \c Summary page. The 318 \c Fields page contains the \c CheckBox, \c ComboBox, 319 \c LineEdit, \c PathChooser, and \c Spacer widgets. For 320 more information about the widgets, see 321 \l{Available Widgets}. 322 323 \endlist 324 325 \li The \c generators section specifies the files to be added to the 326 project: 327 328 \code 329 "generators": 330 [ 331 { 332 "typeId": "File", 333 "data": 334 [ 335 { 336 "source": "file.h", 337 "target": "%{HdrPath}", 338 "openInEditor": true 339 }, 340 { 341 "source": "file.cpp", 342 "target": "%{SrcPath}", 343 "openInEditor": true 344 } 345 ] 346 \endcode 347 348 \list 349 350 \li \c typeId specifies the type of the generator. Currently, 351 only \c File or \c Scanner is supported. 352 353 \li \c data allows to configure the generator further. 354 \endlist 355 356 \endlist 357 358 \endlist 359 360 \section1 Values Available to the Wizard 361 362 In addition to properties taken from the \c {wizard.json} file itself (see 363 \l{Creating Wizards}), \QC makes some information available to all JSON 364 based wizards: 365 366 \list 367 \li \c WizardDir is the absolute path to the \c {wizard.json} file. 368 369 \li \c Features lists all features available via any of the kits 370 configured in \QC. 371 372 \li \c Plugins contains a list of all plugins running in the current 373 instance of \QC. 374 375 \li \c Platform contains the platform selected in the \uicontrol File > 376 \uicontrol {New File or Project} dialog. This value may be empty. 377 \endlist 378 379 The following information is only available when the wizard was triggered 380 via the context menu of a node in the \uicontrol Projects view: 381 382 \list 383 \li \c InitialPath with the path to the selected node. 384 385 \li \c ProjectExplorer.Profile.Ids contains a list of Kits configured 386 for the project of the selected node. 387 \endlist 388 389 \section1 Available Pages 390 391 You can add predefined pages to wizards by specifying them in the \c pages 392 section of a wizard.json file. 393 394 \section2 Field Page 395 396 A Field page has the \c typeId value \c Field and contains widgets. For more 397 information about widget definitions, see \l{Available Widgets}. 398 399 \code 400 "pages": 401 [ 402 { 403 "trDisplayName": "Define Class", 404 "trShortTitle": "Details", 405 "typeId": "Fields", 406 "data" : 407 [ 408 { 409 "name": "Class", 410 "trDisplayName": "Class name:", 411 "mandatory": true, 412 "type": "LineEdit", 413 "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" } 414 }, 415 ... 416 ], 417 \endcode 418 419 \section2 File Page 420 421 A File page has the \c typeId value \c File. You can leave out the \c data 422 key or assign an empty object to it. 423 424 \code 425 { 426 "trDisplayName": "Location", 427 "trShortTitle": "Location", 428 "typeId": "File" 429 }, 430 \endcode 431 432 The page evaluates \c InitialFileName and \c InitialPath from the wizard to 433 set the initial path and filename. The page sets \c TargetPath to the full 434 path of the file to be created. 435 436 \section2 Form Page 437 438 A Form page has the \c typeId value \c Form. You can leave out the \c data 439 key or assign an empty object to it. 440 441 \code 442 { 443 "trDisplayName": "Choose a Form Template", 444 "trShortTitle": "Form Template", 445 "typeId": "Form" 446 }, 447 \endcode 448 449 The page sets \c FormContents to an array of strings with the form contents. 450 451 \section2 Kits 452 453 A Kits page has the \c typeId value \c Kits. The \c data section of a Kits 454 page contains an object with the following settings: 455 456 \list 457 \li \c projectFilePath with the path to the project file. 458 459 \li \c requiredFeatures with a list of strings or objects that describe 460 the features that a kit must provide to be listed on the page. 461 462 When a string is found, this feature must be set. When using an 463 object instead, the following settings are checked: 464 465 \list 466 \li \c feature, which must be a string (that will have all 467 \c {%\{<VariableName\}} expanded). 468 469 \li \c condition, which must evaluate to \c true or \c false and 470 can be used to discount the feature from the list. 471 \endlist 472 473 \li \c preferredFeatures with a list in the same format as 474 requiredFeatures. Any kit matching all features listed in 475 \c preferredFeatures (in addition to \c requiredFeatures) will be 476 pre-selected on this page. 477 \endlist 478 479 \code 480 { 481 "trDisplayName": "Kit Selection", 482 "trShortTitle": "Kits", 483 "typeId": "Kits", 484 "enabled": "%{IsTopLevelProject}", 485 "data": { "projectFilePath": "%{ProFileName}" } 486 }, 487 \endcode 488 489 The page evaluates \c {%\{Platform\}} to set the platform selected in 490 \uicontrol File > \uicontrol {New File or Project}. 491 492 493 494 \section2 Project 495 496 A Project page has the \c typeId value \c Project. It contains no data or an 497 object with the \c trDescription property which will be shown on the 498 generated page. \c trDescription defaults to \c {%\{trDescription\}}, which 499 is filled in with the information taken from the \c trDescription 500 field of the \c {wizard.json} file. 501 502 \code 503 { 504 "trDisplayName": "Project Location", 505 "trShortTitle": "Location", 506 "typeId": "Project", 507 "data": { "trDescription": "A description of the wizard" } 508 }, 509 \endcode 510 511 The page evaluates \c InitialPath to set the initial project path. The page 512 sets \c ProjectDirectory and \c TargetPath to the project directory. 513 514 \section2 Summary 515 516 A Summary page has the \c typeId value \c Summary. It contains no data or 517 an empty object. 518 519 \code 520 { 521 "trDisplayName": "Project Management", 522 "trShortTitle": "Summary", 523 "typeId": "Summary" 524 } 525 \endcode 526 527 The page sets \c IsSubproject to an empty string if this is a toplevel 528 project and to \c yes otherwise. It sets \c VersionControl to the ID of the 529 version control system in use. 530 531 \section2 VcsCommand 532 533 The VcsCommand page runs a set of version control operations and displays 534 the results. 535 536 The \c data section of this page takes an object with the following keys: 537 538 \list 539 \li \c vcsId with the id of the version control system to be used. 540 541 \li \c trRunMessage with the message to be shown while the version 542 control is running. 543 544 \li \c extraArguments with a string or a list of strings defining 545 extra arguments passed to the version control checkout command. 546 547 \li \c repository with the URL to check out from the version control 548 system. 549 550 \li \c baseDirectory with the directory to run the checkout operation 551 in. 552 553 \li \c checkoutName with the subdirectory that will be created to hold 554 the checked out data. 555 556 \li \c extraJobs with a list of objects defining additional commands to 557 run after the initial checkout. This can be used to customize the 558 repository further by for example adding additional remote 559 repositories or setting configuration variables of the version 560 control system. 561 562 Each \c extraJob is defined by an object with the following 563 settings: 564 565 \list 566 \li \c skipIfEmpty will cause empty arguments to be silently 567 removed from the command to be run if set to \c true. 568 Defaults to \c true. 569 570 \li \c directory with the working directory of the command to 571 be run. This defaults to the value of \c baseDirectory. 572 573 \li \c command with the command to be run. 574 575 \li \c arguments with the arguments to pass to \c command. 576 577 \li \c timeOutFactor can be used to provide for longer than 578 default timeouts for long-running commands. 579 580 \li \c enabled which will be evaluated to decide whether or 581 not to actually execute this job. 582 \endlist 583 \endlist 584 585 \section2 VcsConfiguration 586 587 The VcsConfiguration page asks the user to configure a version control 588 system and only enables the \uicontrol Next button once the configuration 589 is successful. 590 591 The \c data section of this page takes an object with the \c vcsId key. 592 This setting defines the version control system that will be configured. 593 594 \section1 Available Widgets 595 596 You can add the following widgets on a Field page: 597 598 \list 599 \li Check Box 600 \li Combo Box 601 \li Label 602 \li Line Edit 603 \li Path Chooser 604 \li Spacer 605 \li Text Edit 606 \endlist 607 608 \note Only the the settings documented in the following sections are 609 supported in wizards. 610 611 Specify the following settings for each widget: 612 613 \list 614 615 \li \c name specifies the widget name. This name is used as the variable 616 name to access the value again. 617 618 \li \c trDisplayName specifies the label text visible in the UI (if 619 \c span is not \c true). 620 621 \li \c type specifies the type of the widget: \c CheckBox, \c ComboBox, 622 \c Label, \c LineEdit, \c PathChooser, \c Spacer, and \c TextEdit. 623 624 \li \c trToolTip specifies a tool tip to show when hovering the field 625 with the mouse. 626 627 \li \c isComplete is evaluated for all fields to decide whether the 628 \uicontrol Next button of the wizard is available or not. All fields 629 must have their \c isComplete evaluate to \c true for this to 630 happen. This setting defaults to \c true. 631 632 \li \c trIncompleteMessage is shown when the field's \c isComplete was 633 evaluated to \c false. 634 635 \li \c persistenceKey makes the user choice persistent. The value is 636 taken to be a settings key. If the user changes the default 637 value of the widget, the user-provided value is stored and will 638 become the new default value the next time the wizard is run. 639 640 \li \c data specifies settings for the widget: 641 642 \list 643 644 \li \c visible is set to \c true if the widget is visible, otherwise 645 it is set to \c false. By default, it is set to \c true. 646 647 \li \c enabled is set to \c true if the widget is enabled, otherwise 648 it is set to \c false. By default, it is set to \c true. 649 650 \li \c mandatory is set to \c true if this widget must have a value 651 for the \uicontrol Next button to become enabled. By default, it 652 is set to \c true. 653 654 \li \c span is set to hide the label and to span the form. By 655 default, it is set to \c false. For more information, see 656 \l{Using Variables in Wizards}. 657 658 \endlist 659 660 The additional settings available for a particular widget are described 661 in the following sections. 662 663 \endlist 664 665 \section2 Check Box 666 667 \code 668 { 669 "name": "IncludeQObject", 670 "trDisplayName": "Include QObject", 671 "type": "CheckBox", 672 "data": 673 { 674 "checkedValue": "QObject", 675 "uncheckedValue": "", 676 "checked": "%{JS: value('BaseCB') === 'QObject' ? 'true' : 'false'}" 677 } 678 }, 679 \endcode 680 681 \list 682 683 \li \c checkedValue specifies the value to set when the check box is 684 enabled. By default, set to \c true. 685 686 \li \c uncheckedValue specifies the value to set when the check box is 687 disabled. By default, set to \c false. 688 689 \li \c checked is set to \c true if the check box is enabled, otherwise 690 \c{false}. 691 692 \endlist 693 694 \section2 List 695 696 \note The Combo Box and Icon List types are both variations of the List type, 697 and therefore they can have the same properties. 698 699 \code 700 { 701 "name": "BaseCB", 702 "trDisplayName": "Base class:", 703 "type": "ComboBox", 704 "data": 705 { 706 "items": [ { "trKey": "<Custom>", "value": "" }, 707 "QObject", "QWidget", "QMainWindow", "QDeclarativeItem", "QQuickItem" ] 708 } 709 }, 710 \endcode 711 or 712 \code 713 { 714 "name": "ChosenBuildSystem", 715 "trDisplayName": "Choose your build system:", 716 "type": "IconList", 717 "data": 718 { 719 "items": [ 720 { "trKey": "Qbs", "value": "qbs", "icon": "qbs_icon.png", "trToolTip": "Building with Qbs." }, 721 { "trKey": "QMake", "value": "qmake", "icon": "qmake_icon.png", "trToolTip": "Building with QMake." } 722 ] 723 } 724 }, 725 \endcode 726 727 \list 728 729 \li \c items specifies a list of items to put into the list type. The 730 list can contain both JSON objects and plain strings. 731 For JSON objects, define \c trKey and \c value pairs, where the 732 \c trKey is the list item visible to users and \c value contains 733 the data associated with the item. 734 In addition, you can use \c icon to specify an icon for the list 735 item and \c trToolTip to specify a tooltip for it. 736 737 \li \c index specifies the index to select when the list type is 738 enabled. By default, it is set to \c 0. 739 740 \li \c disabledIndex specifies the index to show if the list type is 741 disabled. 742 743 \endlist 744 745 \section2 Label 746 747 \code 748 { 749 "name": "LabelQQC_2_0", 750 "type": "Label", 751 "span": true, 752 "visible": "%{JS: value('CS') === 'QQC_2_0'}", 753 "data": 754 { 755 "wordWrap": true, 756 "trText": "Creates a deployable Qt Quick 2 application using Qt Quick Controls.", 757 } 758 }, 759 \endcode 760 761 \list 762 763 \li \c wordWrap is set to \c true to enable word wrap. By default, it is 764 set to \c{false}. 765 766 \li \c trText contains the label text to display. 767 768 \endlist 769 770 \section2 Line Edit 771 772 \code 773 { 774 "name": "Class", 775 "trDisplayName": "Class name:", 776 "mandatory": true, 777 "type": "LineEdit", 778 "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" } 779 }, 780 { 781 "name": "BaseEdit", 782 "type": "LineEdit", 783 "enabled": "%{JS: value('BaseCB') === '' ? 'true' : 'false'}", 784 "mandatory": false, 785 "data": 786 { 787 "trText": "%{BaseCB}", 788 "trDisabledText": "%{BaseCB}", 789 "historyId": "EditValues", 790 "restoreLastHistoryItem": false 791 } 792 }, 793 \endcode 794 795 \list 796 797 \li \c trText specifies the default text to display. 798 799 \li \c trDisabledText specifies the text to display in a disabled field. 800 801 \li \c trPlaceholder specifies the placeholder text. 802 803 \li \c validator specifies a QRegularExpression to validate the line 804 edit against. 805 806 \li \c fixup specifies a variable that is used to fix up the string. 807 For example, to turn the first character in the line edit to upper 808 case. 809 810 \li \c isPassword is a boolean value that specifies that the line edit 811 contains a password, which will be masked. 812 813 \li \c historyId is a key that specifies the name for a list of items 814 for the history completer. 815 816 \li \c restoreLastHistoryItem is a boolean that specifies that the 817 last history item is automatically set as the default text in 818 the line edit. This key can only be set to true if \c historyId 819 is also set. 820 821 \endlist 822 823 \section2 Path Chooser 824 825 \code 826 { 827 "name": "Path", 828 "type": "PathChooser", 829 "trDisplayName": "Path:", 830 "mandatory": true, 831 "data": 832 { 833 "kind": "existingDirectory", 834 "basePath": "%{InitialPath}", 835 "path": "%{InitialPath}" 836 } 837 }, 838 \endcode 839 840 \list 841 842 \li \c path specifies the selected path. 843 844 \li \c basePath specifies a base path that lookups are relative to. 845 846 \li \c kind defines what to look for: \c existingDirectory, 847 \c directory, \c file, \c saveFile, \c existingCommand, \c command, 848 or \c any. 849 850 \endlist 851 852 \section2 Spacer 853 854 \code 855 { 856 "name": "Sp1", 857 "type": "Spacer", 858 "data": 859 { 860 "factor": 2 861 } 862 }, 863 \endcode 864 865 The \c factor setting specifies the factor (an integer) to multiply the 866 layout spacing for this spacer. 867 868 \section2 Text Edit 869 870 \code 871 { 872 "name": "TextField", 873 "type": "TextEdit", 874 "data" : 875 { 876 "trText": "This is some text", 877 "richText": true 878 } 879 } 880 \endcode 881 882 \list 883 884 \li \c trText specifies the text to display. 885 886 \li \c trDisabledText specifies the text to display when the text edit 887 is disabled. 888 889 \li \c richText is set to \c true for rich text, otherwise \c{false}. 890 891 \endlist 892 893 \section1 Available Generators 894 895 \QC supports two different generators for JSON wizards. 896 897 \section2 File Generator 898 899 A \c File generator expects a list of objects in its \c data section. Each 900 object defines one file to be processed and copied into the 901 \c {%\{TargetPath\}} (or any other location). 902 903 Each file object can take the following settings: 904 905 \list 906 \li \c source specifies the path and filename of the template file 907 relative to the directory containing the \c {wizard.json} file. 908 909 If \c source is unset, it is assumed that the file with the name 910 given in \c target is generated by some other means. This is useful 911 to for example specify the correct file to open as a project after 912 checking out data from a version control system. 913 914 \li \c target specifies the location of the generated file, either 915 absolute or relative to \c %{TargetPath}, which is usually set by 916 one of the wizard pages. 917 918 \li \c openInEditor opens the file in the appropriate editor if it is 919 set to \c true. This setting defaults to \c false. 920 921 \li \c openAsProject opens the project file in \QC if it is set to 922 \c true. This setting defaults to \c false. 923 924 \li \c isBinary treats the file as a binary and prevents replacements 925 from being done in the file if set to \c true. This setting 926 defaults to \c false. 927 928 \li \c condition generates the file if the condition 929 returns \c true. This setting defaults to \c true. For more 930 information, see \l{Using Variables in Wizards}. 931 932 \endlist 933 934 \section2 Scanner Generator 935 936 A \c Scanner generator scans the \c {%\{TargetPath\}} and produces a list 937 of all files found there. 938 939 The \c Scanner generator takes one object in its \c data section with the 940 following settings: 941 942 \list 943 944 \li \c binaryPattern is a regular expression that will be matched 945 against all file names found. Any match will be marked as a binary 946 file and template substitution will be skipped for this file. This 947 setting defaults to an empty pattern, so no files will be marked as 948 binary. 949 950 \li \c subdirectoryPatterns is a list of regular expression patterns. 951 Any directory matching one of these patterns will be scanned as well 952 as the top level directory. This setting defaults to an empty list 953 and no subdirectories will be scanned. 954 955 \endlist 956//! [json wizards] 957*/ 958
