diff --git a/docs/atl/reference/ccomvariant-class.md b/docs/atl/reference/ccomvariant-class.md index cb97f860f4d..f53db737df1 100644 --- a/docs/atl/reference/ccomvariant-class.md +++ b/docs/atl/reference/ccomvariant-class.md @@ -4,7 +4,6 @@ title: "CComVariant class" ms.date: "11/04/2016" f1_keywords: ["CComVariant", "ATLCOMCLI/ATL::CComVariant", "ATLCOMCLI/ATL::CComVariant::CComVariant", "ATLCOMCLI/ATL::CComVariant::Attach", "ATLCOMCLI/ATL::CComVariant::ChangeType", "ATLCOMCLI/ATL::CComVariant::Clear", "ATLCOMCLI/ATL::CComVariant::Copy", "ATLCOMCLI/ATL::CComVariant::CopyTo", "ATLCOMCLI/ATL::CComVariant::Detach", "ATLCOMCLI/ATL::CComVariant::GetSize", "ATLCOMCLI/ATL::CComVariant::ReadFromStream", "ATLCOMCLI/ATL::CComVariant::SetByRef", "ATLCOMCLI/ATL::CComVariant::WriteToStream"] helpviewer_keywords: ["VARIANT macro", "CComVariant class", "VARIANT macro, ATL"] -ms.assetid: 4d31149c-d005-44b5-a509-10f84afa2b61 --- # `CComVariant` class @@ -52,7 +51,7 @@ class CComVariant : public tagVARIANT ## Remarks -`CComVariant` wraps the `VARIANT` and `VARIANTARG` type, which consists of a union and a member indicating the type of the data stored in the union. VARIANTs are typically used in Automation. +`CComVariant` wraps the `VARIANT` and `VARIANTARG` type, which consists of a union and a member indicating the type of the data stored in the union. `VARIANT`s are typically used in Automation. `CComVariant` derives from the `VARIANT` type so it can be used wherever a `VARIANT` can be used. You can, for example, use the `V_VT` macro to extract the type of a `CComVariant` or you can access the `vt` member directly just as you can with a `VARIANT`. @@ -63,7 +62,7 @@ class CComVariant : public tagVARIANT ## Requirements -**Header:** atlcomcli.h +**Header:** `atlcomcli.h` ## `CComVariant::Attach` @@ -183,7 +182,7 @@ HRESULT ChangeType(VARTYPE vtNew, const VARIANT* pSrc = NULL); [in] The new type for the `CComVariant` object. *`pSrc`*\ -[in] A pointer to the `VARIANT` whose value is converted to the new type. The default value is NULL, meaning the `CComVariant` object is converted in place. +[in] A pointer to the `VARIANT` whose value is converted to the new type. The default value is `NULL`, meaning the `CComVariant` object is converted in place. ### Return value @@ -270,7 +269,7 @@ The contents of the `VARIANT` referenced by *`pDest`* are automatically cleared ## `CComVariant::GetSize` -For simple-fixed size VARIANTs, this method returns the **`sizeof`** value for the underlying data type plus `sizeof(VARTYPE)`. +For simple-fixed size `VARIANT`s, this method returns the **`sizeof`** value for the underlying data type plus `sizeof(VARTYPE)`. ```cpp ULONG GetSize() const; @@ -282,9 +281,9 @@ The size in bytes of the current contents of the `CComVariant` object. ### Remarks -If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is NULL, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. +If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is `NULL`, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. -In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the null character plus `sizeof(VARTYPE)`. If the `VARIANT` cannot be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. +In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the `NULL` character plus `sizeof(VARTYPE)`. If the `VARIANT` can’t be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. The size returned by this method matches the number of bytes used by [`CComVariant::WriteToStream`](#writetostream) under successful conditions. diff --git a/docs/build/reference/analyze-code-analysis.md b/docs/build/reference/analyze-code-analysis.md index e2f0739798b..c2830679776 100644 --- a/docs/build/reference/analyze-code-analysis.md +++ b/docs/build/reference/analyze-code-analysis.md @@ -1,8 +1,8 @@ --- title: "/analyze (Code analysis)" description: "The Microsoft C++ compiler /analyze option syntax and usage." -ms.date: 10/19/2021 -f1_keywords: ["VC.Project.VCCLCompilerTool.EnablePREfast", "/analyze", "VC.Project.VCCLCompilerTool.PREfastAdditionalOptions", "VC.Project.VCCLCompilerTool.PREfastAdditionalPlugins"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.EnablePREfast", "/analyze", "VC.Project.VCCLCompilerTool.PREfastAdditionalOptions", "VC.Project.VCCLCompilerTool.PREfastAdditionalPlugins", "VC.Project.VCCLCompilerTool.DisableAnalyzeExternal", "VC.Project.VCCLCompilerTool.AnalyzeExternalRuleset"] helpviewer_keywords: ["/analyze compiler option [C++]", "-analyze compiler option [C++]", "analyze compiler option [C++]"] ms.assetid: 81da536a-e030-4bd4-be18-383927597d08 --- @@ -135,7 +135,7 @@ Then, use compiler option `/analyze:plugin EspXEngine.dll` to use the EspXEngine #### External file analysis options -Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. By using the **`/external:I`**, **`/external:env`**, or **`/external:anglebrackets`** options, directories can be specified as "external" directories. Any files that are included by using `#include`from an external directory or one of its subdirectories are considered as external headers. For more information, see [`/external` (External headers diagnostics)](external-external-headers-diagnostics.md). +Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. Use the **`/external:I`**, **`/external:env`**, or **`/external:anglebrackets`** options to specify directories as "external" directories. Any files that are included by using `#include`from an external directory or its subdirectories are considered as external headers. For more information, see [`/external` (External headers diagnostics)](external-external-headers-diagnostics.md). Code analysis provides these options to control analysis of external files: @@ -206,14 +206,14 @@ Specifies the current project directory. If the ruleset (or an item it includes) Specifies a semicolon-separated list of ruleset search paths. If the ruleset (or an item it includes) is a file name, then the compiler first looks for the file under the *`project_directory`* specified by **`/analyze:projectdirectory`**, if any, followed by the specified *`ruleset_directories`*. This option is available starting in Visual Studio 2019 version 16.9. **`/analyze:ruleset`** *`ruleset_files`*\ -Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient. That's because the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled. +Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled. ::: moniker-end ::: moniker range="msvc-150" **`/analyze:ruleset`** *`ruleset_file`*\ -Specifies a ruleset file to use for analysis. This option can make analysis more efficient. That's because the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled. +Specifies a ruleset file to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled. ::: moniker-end @@ -267,6 +267,26 @@ For more information, see [Code analysis for C/C++ overview](../../code-quality/ 1. Modify one or more of the **Code Analysis** properties. +1. Choose **OK** or **Apply** to save your changes. + +::: moniker range=">=msvc-160" + +To set external file analysis options in Visual Studio 2019 version 16.10 and later: + +1. Open the project's **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **C/C++** > **External Includes** property page. + +1. Set properties: + + - **Disable Code Analysis for External Headers** sets the **`/analyze:external-`** option. + + - **Analysis Ruleset for External Headers** sets the **`/analyze:external:ruleset path`** option. + +1. Choose **OK** or **Apply** to save your changes. + +::: moniker-end + ### To set this compiler option programmatically 1. See . diff --git a/docs/build/reference/c-cpp-prop-page.md b/docs/build/reference/c-cpp-prop-page.md index a5744b0b896..815be7b6941 100644 --- a/docs/build/reference/c-cpp-prop-page.md +++ b/docs/build/reference/c-cpp-prop-page.md @@ -1,8 +1,9 @@ --- title: "C/C++ Project Properties (Visual Studio)" description: "Reference guide to the Visual Studio Microsoft C/C++ project Property Pages properties." -ms.date: 09/03/2020 +ms.date: 02/17/2022 ms.topic: "article" +f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalModuleDirectories", "VC.Project.VCCLCompilerTool.ScanSourceForModuleDependencies"] ms.assetid: 16375038-4917-4bd0-9a2a-26343c1708b7 --- # C/C++ Property Pages @@ -13,15 +14,37 @@ The following property pages are found under **Project** > **Properties** > **Co ### Additional Include Directories -Specifies one or more directories to add to the include path; separate with semi-colons if more than one. Sets [`/I` (Additional include directories)](i-additional-include-directories.md). +Specifies one or more directories to add to the include path. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/I` (Additional include directories)](i-additional-include-directories.md) compiler option. ### Additional #using Directories -Specifies one or more directories (separate directory names with a semicolon) to be searched to resolve names passed to a #using directive. Sets [`/AI`](ai-specify-metadata-directories.md). +Specifies one or more directories to search to resolve names passed to a `#using` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/AI`](ai-specify-metadata-directories.md) compiler option. + +### Additional BMI Directories + +Specifies one or more directories to search to resolve names passed to an `import` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the **`/ifcSearchDir[path]`** compiler option. + +### Additional Module Dependencies + +Specifies one or more modules to use to resolve names passed to an `import` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/reference`](module-reference.md) compiler option. + +### Additional Header Unit Dependencies + +Specifies one or more header units to use to resolve names passed to an `import` header directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/headerUnit`](headerunit.md) compiler option. + +### Scan Sources for Module Dependencies + +When set to **Yes**, the compiler scans all C++ sources, not just module interface and header unit sources, for module and header units dependencies. The build system builds the full dependencies graph, which ensures that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, any header file that's specified in a [`header-units.json`](header-unit-json-reference.md) file in the same directory as the header file is compiled into a header unit. + +Files that have the extension *`.ixx`*, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/export)**, are always scanned. + +### Translate Includes to Imports + +When set to **Yes**, the compiler treats a `#include` directive as an `import` directive if certain conditions are met: The header file is specified in a *`header-units.json`* file in the same directory, and a compiled header unit (an *`.ifc`* file) is available for the header file. Otherwise, the header file is treated as a normal `#include`. The *`header-units.json`* file is used to build header units for each `#include` without symbol duplication. When combined with **Scan Sources for Module Dependencies**, the compiler automatically finds all of the header files that can be compiled into header units. This property sets the [`/translateInclude`](translateinclude.md) compiler option. ### Debug Information Format -Specifies the type of debugging information generated by the compiler. This property requires compatible linker settings. Sets [`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md). +Specifies the type of debugging information generated by the compiler. This property requires compatible linker settings. Sets [`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md) compiler options. #### Choices @@ -90,7 +113,11 @@ Additional Security Development Lifecycle (SDL) recommended checks; includes ena ### Multi-processor Compilation -Multi-processor Compilation. +Enable multi-processor compilation. Sets the [`/MP`](mp-build-with-multiple-processes.md) compiler option. + +### Enable Address Sanitizer + +Compiles and links the program with AddressSanitizer instrumentation. This property currently supports x86 and x64 target builds. Sets the [`/fsanitize`](fsanitize.md) compiler option. ## C/C++ Optimization Properties @@ -280,7 +307,7 @@ Sets the floating point model. Sets [`/fp:precise`, `/fp:strict`, `/fp:fast`](fp - **Precise** - Default. Improves the consistency of floating-point tests for equality and inequality. - **Strict** - The strictest floating-point model. **`/fp:strict`** causes **`fp_contract`** to be OFF and **`fenv_access`** to be ON. **`/fp:except`** is implied and can be disabled by explicitly specifying **`/fp:except-`**. When used with **`/fp:except-`**, **`/fp:strict`** enforces strict floating-point semantics but without respect for exceptional events. -- **Fast** - Creates the fastest code in the majority of cases. +- **Fast** - Creates the fastest code in most cases. ### Enable Floating Point Exceptions @@ -421,6 +448,28 @@ Specifies level of browse information in *`.bsc`* file. Sets [`/FR`](fr-fr-creat Specifies optional name for browser information file. Sets [`/FR`\](fr-fr-create-dot-sbr-file.md). +## External Includes + +### Treat Files Included with Angle Brackets as External + +Specifies whether to treat files included with angle brackets as external. Set this property to **Yes** to set the [`/external:anglebrackets`](external-external-headers-diagnostics.md) compiler option. + +### External Header Warning Level + +Select how strict you want the compiler to be about code errors in external headers. This property sets the [`/external:Wn`](external-external-headers-diagnostics.md) compiler option. If this value is set to **Inherit Project Warning Level** or the default, other **`/external`** options are ignored. + +### Template Diagnostics in External Headers + +Specifies whether to evaluate the warning level across a template instantiation chain. Set this property to **Yes** to set the [`/external:templates-`](external-external-headers-diagnostics.md) compiler option. + +### Disable Code Analysis for External Headers + +Disables code analysis for external headers. Sets the [`/analyze:external-`](analyze-code-analysis.md) compiler option. + +### Analysis Ruleset for External Headers + +Specifies a code analysis ruleset override for external headers. If not specified, the Code Analysis setting is used. Sets the [`/analyze:external:ruleset path`](analyze-code-analysis.md) compiler option. + ## C/C++ Advanced Properties ### Calling Convention diff --git a/docs/build/reference/compiler-option-warning-level.md b/docs/build/reference/compiler-option-warning-level.md index 4b89c26f118..251396f31fb 100644 --- a/docs/build/reference/compiler-option-warning-level.md +++ b/docs/build/reference/compiler-option-warning-level.md @@ -1,8 +1,8 @@ --- title: "/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level)" description: "Reference for the Microsoft C/C++ compiler options: /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, and /WX." -ms.date: "01/31/2020" -f1_keywords: ["VC.Project.VCCLCompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarningLevel", "VC.Project.VCCLWCECompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarnAsError", "VC.Project.VCCLWCECompilerTool.WarnAsError", "/wx", "VC.Project.VCCLWCECompilerTool.WarningLevel", "/wall", "VC.Project.VCCLCompilerTool.TreatSpecificWarningsAsErrors", "/Wv", "/w0", "/w1", "/w2", "/w3", "/w4", "/wd", "/we", "/wo"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarningLevel", "VC.Project.VCCLWCECompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarnAsError", "VC.Project.VCCLWCECompilerTool.WarnAsError", "VC.Project.VCCLCompilerTool.WarningVersion", "/wx", "VC.Project.VCCLWCECompilerTool.WarningLevel", "/wall", "VC.Project.VCCLCompilerTool.TreatSpecificWarningsAsErrors", "/Wv", "/w0", "/w1", "/w2", "/w3", "/w4", "/wd", "/we", "/wo"] helpviewer_keywords: ["/W1 compiler option [C++]", "w compiler option [C++]", "-wo compiler option [C++]", "Warning Level compiler option", "W1 compiler option [C++]", "-we compiler option [C++]", "/WX compiler option [C++]", "-wd compiler option [C++]", "WX compiler option [C++]", "wo compiler option [C++]", "Wall compiler option [C++]", "/w compiler option", "W2 compiler option [C++]", "-W2 compiler option [C++]", "wd compiler option [C++]", "/we compiler option [C++]", "we compiler option [C++]", "-W1 compiler option [C++]", "-W4 compiler option [C++]", "-Wall compiler option [C++]", "/Wall compiler option [C++]", "-W0 compiler option [C++]", "W0 compiler option [C++]", "-WX compiler option [C++]", "/wo compiler option [C++]", "W4 compiler option [C++]", "W3 compiler option [C++]", "/wd compiler option [C++]", "warnings, as errors compiler option", "/W3 compiler option [C++]", "/W0 compiler option [C++]", "/W4 compiler option [C++]", "-W3 compiler option [C++]", "-w compiler option [C++]", "/W2 compiler option [C++]", "/Wv compiler option [C++]"] --- # /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level) diff --git a/docs/build/reference/external-external-headers-diagnostics.md b/docs/build/reference/external-external-headers-diagnostics.md index 9423c65d7b2..566189a56f1 100644 --- a/docs/build/reference/external-external-headers-diagnostics.md +++ b/docs/build/reference/external-external-headers-diagnostics.md @@ -1,8 +1,8 @@ --- title: "/external (External headers diagnostics)" description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage." -ms.date: 07/02/2021 -f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external"] +ms.date: 02/17/2022 +f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external", "VC.Project.VCCLCompilerTool.ExternalDirectoriesEnv", "VC.Project.VCCLCompilerTool.ExternalIncludeDirectories", "VC.Project.VCCLCompilerTool.ExternalWarningLevel", "VC.Project.VCCLCompilerTool.TreatExternalTemplatesAsInternal"] helpviewer_keywords: ["/external compiler option [C++]", "-external compiler option [C++]", "external compiler option [C++]"] --- # `/external` (External headers diagnostics) @@ -18,7 +18,7 @@ Use external header options (Not required in 16.10 and later): Specify external headers: > **`/external:anglebrackets`**\ -> **`/external:env:`**_`var`_\ +> **`/external:env:`***`var`*\ > **`/external:I`** *`path`* Specify diagnostics behavior: @@ -40,7 +40,7 @@ Treats all headers included by `#include
`, where the *`header`* file is **`/external:I`** *`path`*\ Defines a root directory that contains external headers. All recursive subdirectories of *`path`* are considered external, but only the *`path`* value is added to the list of directories the compiler searches for include files. The space between **`/external:I`** and *`path`* is optional. Directories that include spaces must be enclosed in double quotes. A directory may be an absolute path or a relative path. -**`/external:env:`**_`var`_\ +**`/external:env:`***`var`*\ Specifies the name of an environment variable *`var`* that holds a semicolon-separated list of external header directories. It's useful for build systems that rely on environment variables such as `INCLUDE`, which you use to specify the list of external include files. Or, `CAExcludePath`, for files that shouldn't be analyzed by `/analyze`. For example, you can specify `/external:env:INCLUDE` to make every directory in `INCLUDE` an external header directory at once. It's the same as using **`/external:I`** to specify the individual directories, but much less verbose. There should be no space between *`var`* and **`/external:env:`**. **`/external:Wn`**\ @@ -97,7 +97,7 @@ cl /EHsc /I include_dir /W4 program.cpp As expected, this sample generates a warning: -```console +```Output program.cpp include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'int' to 'const T', signed/unsigned mismatch with @@ -167,17 +167,41 @@ Some warnings emitted by the compiler's back-end code generation aren't affected ### To set this compiler option in the Visual Studio development environment +In Visual Studio 2019 version 16.10 and later: + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **VC++ Directories** property page. + +1. Set the **External Include Directories** property to specify the IDE equivalent of the **`/external:I path`** option for each semicolon-delimited path. + +1. Select the **Configuration Properties** > **C/C++** > **External Includes** property page. + +1. Set properties: + + - Set **Treat Files Included with Angle Brackets as External** to **Yes** to set the **`/external:anglebrackets`** option. + + - **External Header Warning Level** allows you to set the **`/external:Wn`** option. If this value is set to **Inherit Project Warning Level** or the default, other **`/external`** options are ignored. + + - Set **Template Diagnostics in External Headers** to **Yes** to set the **`/external:templates-`** option. + +1. Choose **OK** or **Apply** to save your changes. + +In versions of Visual Studio before Visual Studio 2019 version 16.10: + 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Enter the compiler options[\*](#note_experimental) in the **Additional Options** box. +1. Enter the **`/experimental:external`** option and other **`/external`** compiler options in the **Additional Options** box. + +1. Choose **OK** or **Apply** to save your changes. ### To set this compiler option programmatically - See . -\* Add the `/experimental:external` option to enable the external headers options in versions of Visual Studio before Visual Studio 2019 version 16.10. +\* Add the **`/experimental:external`** option to enable the external headers options in versions of Visual Studio before Visual Studio 2019 version 16.10. ## See also diff --git a/docs/build/reference/fsanitize.md b/docs/build/reference/fsanitize.md index 8106ba7c22d..be1a27702fb 100644 --- a/docs/build/reference/fsanitize.md +++ b/docs/build/reference/fsanitize.md @@ -1,8 +1,8 @@ --- description: "Learn more about the /fsanitize (enable sanitizers) compiler option" title: "/fsanitize (Enable sanitizers)" -ms.date: 09/15/2021 -f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize=fuzzer", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib"] +ms.date: 02/17/2022 +f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize=fuzzer", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib", "VC.Project.VCCLCompilerTool.EnableASAN"] helpviewer_keywords: ["/fsanitize [C++]", "-fsanitize=address [C++]", "address sanitizer compiler option [C++]", "/fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib"] --- # `/fsanitize` (Enable sanitizers) diff --git a/docs/build/reference/module-reference.md b/docs/build/reference/module-reference.md index 9315ebc705c..10f51331a99 100644 --- a/docs/build/reference/module-reference.md +++ b/docs/build/reference/module-reference.md @@ -1,8 +1,8 @@ --- title: "/reference (Use named module IFC)" description: "Use the /reference compiler option to create module header units for the header-name or include files specified." -ms.date: 04/13/2020 -f1_keywords: ["/reference"] +ms.date: 02/17/2022 +f1_keywords: ["/reference", "VC.Project.VCCLCompilerTool.AdditionalModuleDependencies"] helpviewer_keywords: ["/reference", "Use named module IFC"] --- # `/reference` (Use named module IFC) @@ -24,7 +24,7 @@ A valid name of an exported primary module interface unit name or full module pa ## Remarks -In most cases you won't need to specify this switch because the project system discovers module dependencies within a solution automatically. +In most cases, you won't need to specify this switch because the project system discovers module dependencies within a solution automatically. The **`/reference`** compiler option requires you enable the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**). The **`/reference`** option is available starting in Visual Studio 2019 version 16.10. diff --git a/docs/build/reference/translateinclude.md b/docs/build/reference/translateinclude.md index f3d21437aa0..fa5cadac9e8 100644 --- a/docs/build/reference/translateinclude.md +++ b/docs/build/reference/translateinclude.md @@ -1,10 +1,10 @@ --- title: "/translateInclude" description: "Use the /translateInclude compiler option to treat #include directives as import statements when an importable header unit is available." -ms.date: 02/11/2022 +ms.date: 02/17/2022 author: "tylermsft" ms.author: "twhitney" -f1_keywords: ["/translateInclude"] +f1_keywords: ["/translateInclude", "VC.Project.VCCLCompilerTool.TranslateIncludes"] helpviewer_keywords: ["/translateInclude", "Translate include directives into import directives"] --- # `/translateInclude` @@ -32,9 +32,13 @@ For an example of how this switch is used, see [Walkthrough: Build and import he To enable `/translateInclude`, in the project properties dialog, set **Translate Includes to Imports**: -1. In the left-hand pane of the project property pages, select **Configuration Properties** > **C/C++** > **General** -1. Change the **Translate Includes to Imports** dropdown to **Yes** -![Screenshot of the Property Pages dialog with the Translate Includes to Imports property highlighted.](../media/vs2019-translate-includes-option.png) +1. In the left-hand pane of the project property pages, select **Configuration Properties** > **C/C++** > **General**. + +1. Change the **Translate Includes to Imports** dropdown to **Yes**. + + ![Screenshot of the Property Pages dialog with the Translate Includes to Imports property highlighted.](../media/vs2019-translate-includes-option.png) + +1. Choose **OK** or **Apply** to save your changes. ## See also diff --git a/docs/build/reference/vcpp-directories-property-page.md b/docs/build/reference/vcpp-directories-property-page.md index e00afe61397..524918f3808 100644 --- a/docs/build/reference/vcpp-directories-property-page.md +++ b/docs/build/reference/vcpp-directories-property-page.md @@ -1,34 +1,34 @@ --- description: "Learn more about: VC++ Directories Property Page (Windows)" title: "VC++ Directories Property Page" -ms.date: "07/17/2019" -f1_keywords: ["VC.Project.VCDirectories.IncludePath", "VC.Project.VCDirectories.ReferencePath", "VC.Project.VCDirectories.SourcePath", "VC.Project.VCDirectories.LibraryWPath", "VC.Project.VCDirectories.ExecutablePath", "VC.Project.VCDirectories.LibraryPath", "VS.ToolsOptionsPages.Projects.VCDirectories", "VC.Project.VCDirectories.ExcludePath"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCDirectories.IncludePath", "VC.Project.VCDirectories.ReferencePath", "VC.Project.VCDirectories.SourcePath", "VC.Project.VCDirectories.LibraryWPath", "VC.Project.VCDirectories.ExecutablePath", "VC.Project.VCDirectories.LibraryPath", "VS.ToolsOptionsPages.Projects.VCDirectories", "VC.Project.VCDirectories.ExcludePath", "VC.Project.VCDirectories.ExternalIncludePath", "VC.Project.VCConfiguration.PublicIncludeDirectories", "VC.Project.VCConfiguration.AllProjectIncludesArePublic", "VC.Project.VCConfiguration.PublicModuleDirectories", "VC.Project.VCConfiguration.AllProjectBMIsArePublic"] helpviewer_keywords: ["VC++ Directories Property Page"] ms.assetid: 428eeef6-f127-4271-b3ea-0ae6f2c3d624 --- # VC++ Directories Property Page (Windows) -Use this property page to tell Visual Studio which directories to use when building the currently-selected project. To set directories for multiple projects in a solution, use a custom property sheet as described in [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). +Use this property page to tell Visual Studio which directories to use when building the currently selected project. To set directories for multiple projects in a solution, use a custom property sheet as described in [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). For the Linux version of this page, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). To access the **VC++ Directories** property page: -1. If the **Solution Explorer** window is not visible, then on the main menu choose **View** > **Solution Explorer**. +1. If the **Solution Explorer** window isn't visible, choose **View** > **Solution Explorer** on the main menu. 1. Right-click on a project node (not the top-level solution) and choose **Properties** to open the **Property Pages** dialog box. 1. Select the **Configuration Properties** > **VC++ Directories** property page. -VC++ Directories properties apply to a project, not the top-level solution node. If you do not see **VC++ Directories** under **Configuration Properties**, select a C++ project node in the **Solution Explorer** window: +VC++ Directories properties apply to a project, not the top-level solution node. If you don't see **VC++ Directories** under **Configuration Properties**, select a C++ project node in the **Solution Explorer** window: ![Screenshot of the Solution Explorer window with the Project node selected.](../media/vcppdir.png "Select the project node to see the VC++ Directories properties") -Note that the **VC++ Directories** property page for cross-platform projects looks different. For information specific to Linux C++ projects, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). +The **VC++ Directories** property page for cross-platform projects looks different. For information specific to Linux C++ projects, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). -If you are not familiar with *project properties* in Visual Studio, you might find it helpful to first read [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you're not familiar with *project properties* in Visual Studio, you might find it helpful to first read [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -The default settings for **VC++ Directories** properties depend on project type. For desktop projects they include the C++ tools locations for a particular Platform Toolset and the Windows SDK location. You can change the **Platform Toolset** and **Windows SDK version** on the **Configuration Properties** > **General** page. +The default settings for **VC++ Directories** properties depend on project type. For desktop projects, they include the C++ tools locations for a particular Platform Toolset and the Windows SDK location. You can change the **Platform Toolset** and **Windows SDK version** on the **Configuration Properties** > **General** page. To view the values for any of the directories: @@ -42,15 +42,15 @@ You now see a dialog box like this: ![Screenshot of the Library Directories dialog.](../media/vcppdir_libdir.png "Dialog to add or remove library paths") -Use this dialog to view the current directories. However, if you want to change or add a directory, it is better to use **Property Manager** to create a property sheet or modify the default user property sheet. For more information, see [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). +Use this dialog to view the current directories. However, if you want to change or add a directory, it's better to use **Property Manager** to create a property sheet or modify the default user property sheet. For more information, see [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). -As shown above, many of the inherited paths are given as macros. To examine the current value of a macro, choose the **Macros** button in the lower right corner of the dialog box. Note that many macros depend on the configuration type. A macro in a debug build might evaluate to a different path than the same macro in a release build. +As shown above, many of the inherited paths are given as macros. To examine the current value of a macro, choose the **Macros** button in the lower right corner of the dialog box. Many macros depend on the configuration type. A macro in a debug build might evaluate to a different path than the same macro in a release build. -You can search for partial or complete matches in the edit box. The following illustration shows all the macros that contain the string "WindowsSDK" and it also shows the current path that the macro evaluates to: +You can search for partial or complete matches in the edit box. The following illustration shows all the macros that contain the string "WindowsSDK". It also shows the current path that each macro evaluates to: ![Screenshot of the Library Directories dialog with the list of macro values displayed.](../media/vcppdir_libdir_macros.png "Dialog to edit macros") -Note: The list is populated as you type. Don't press **Enter**. +This list is populated as you type. Don't press **Enter**. For more information about macros and why you should use them instead of hard-coded paths whenever possible, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -60,35 +60,52 @@ You can define your own macros in two ways: - Set environment variables in a developer command prompt. All environment variables are treated as MSBuild properties/macros. -- Define user macros in a .props file. For more information, see [Property page macros](../working-with-project-properties.md). +- Define user macros in a *`.props`* file. For more information, see [Property page macros](../working-with-project-properties.md). For more information, see [Property inheritance in Visual Studio projects](../project-property-inheritance.md), and these blog posts: [VC++ Directories](/archive/blogs/vsproject/vc-directories), [Visual Studio 2010 C++ Project Upgrade Guide](https://devblogs.microsoft.com/cppblog/visual-studio-2010-c-project-upgrade-guide/). -## Directory Types +## General You can also specify other directories, as follows. -**Executable Directories**
-Directories in which to search for executable files. Corresponds to the **PATH** environment variable. +**Executable Directories**\ +Directories in which to search for executable files. Corresponds to the **`PATH`** environment variable. -**Include Directories**
-Directories in which to search for include files that are referenced in the source code. Corresponds to the **INCLUDE** environment variable. +**Include Directories**\ +Directories in which to search for include files that are referenced in the source code. Corresponds to the **`INCLUDE`** environment variable. -**Reference Directories**
-Directories in which to search for assembly and module (metadata) files that are referenced in the source code by the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. Corresponds to the **LIBPATH** environment variable. +**External Include Directories**\ +Paths for include files to treat as external or system files during compilation. These files are skipped in build up-to-date checks. These paths are also used by the [External Includes](c-cpp-prop-page.md#external-includes) properties. For more information on how to set these options in the IDE, see the [`/external`](../../build/reference/external-external-headers-diagnostics.md) compiler option. -**Library Directories**
-Directories in which to search for libraries (.lib) files; this includes run-time libraries. Corresponds to the **LIB** environment variable. This setting does not apply to .obj files; to link to an .obj file, on the **Configuration Properties** > **Linker** > **General** property page, select **Additional Library Dependencies** and then specify the relative path of the file. For more information, see [Linker property pages](linker-property-pages.md). +**Reference Directories**\ +Directories in which to search for assembly and module (metadata) files that are referenced in the source code by the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. Corresponds to the **`LIBPATH`** environment variable. -**Library WinRT Directories**
+**Library Directories**\ +Directories to search for library (*`.lib`*) files. This search includes run-time libraries. Corresponds to the **`LIB`** environment variable. This setting doesn't apply to *`.obj`* files; to link to an *`.obj`* file, on the **Configuration Properties** > **Linker** > **General** property page, select **Additional Library Dependencies** and then specify the relative path of the file. For more information, see [Linker property pages](linker-property-pages.md). + +**Library WinRT Directories**\ Directories to search for WinRT library files for use in Universal Windows Platform (UWP) apps. -**Source Directories**
+**Source Directories**\ Directories in which to search for source files to use for IntelliSense. -**Exclude Directories**
+**Exclude Directories**\ Before each compilation, Visual Studio queries the timestamp on all files to determine whether any have been modified since the previous compilation. If your project has large stable libraries, you can potentially speed up build times by excluding those directories from the timestamp check. -## Sharing the Settings +## Public Project Content + +**Public Include Directories**\ +One or more directories to automatically add to the include path in projects that reference this project. + +**All Header Files are Public**\ +Specifies whether to automatically add public directories or all project header files to the include path in projects that reference this project. + +**Public C++ Module Directories**\ +One or more directories that contain C++ module or header unit sources to make available automatically to projects that reference this project. + +**All Modules are Public**\ +Specifies whether to make all project modules and header units available automatically to projects that reference this project. + +## Sharing the settings You can share project properties with other users or across multiple computers. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). diff --git a/docs/build/reference/zc-preprocessor.md b/docs/build/reference/zc-preprocessor.md index 6e8587f90ad..fd8708017a4 100644 --- a/docs/build/reference/zc-preprocessor.md +++ b/docs/build/reference/zc-preprocessor.md @@ -1,8 +1,8 @@ --- title: "/Zc:preprocessor (Enable preprocessor conformance mode)" description: "Use the /Zc:preprocessor compiler option to enable compiler support for a standard conforming preprocessor." -ms.date: 09/10/2020 -f1_keywords: ["preprocessor", "/Zc:preprocessor"] +ms.date: 02/17/2022 +f1_keywords: ["preprocessor", "/Zc:preprocessor", "VC.Project.VCCLCompilerTool.PreprocessorStandard"] helpviewer_keywords: ["preprocessor conformance", "/Zc:preprocessor", "Enable preprocessor conformance mode"] --- # `/Zc:preprocessor` (Enable preprocessor conformance mode) @@ -11,7 +11,7 @@ This option enables a token-based preprocessor that conforms to C99 and C++11 an ## Syntax -> **`/Zc:preprocessor`**[**-**] +> **`/Zc:preprocessor`**[**`-`**] ## Remarks @@ -23,9 +23,9 @@ The **`/Zc:preprocessor`** option is available starting in Visual Studio 2019 ve 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. -1. Modify the **Additional Options** property to include *`/Zc:preprocessor`* and then choose **OK**. +1. Modify the **Use Standard Conforming Preprocessor** property and then choose **OK**. ## See also diff --git a/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md b/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md index bd20fa5da09..a1d0acf6c12 100644 --- a/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md +++ b/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fscanf", "fwscanf", "_ftscanf_l", "_fwscanf_l", "_ftscanf", "_fscanf_l"] helpviewer_keywords: ["fscanf function", "fwscanf function", "formatted data [C++], reading from streams", "ftscanf_l function", "_ftscanf_l function", "_fwscanf_l function", "data [CRT], reading from streams", "_fscanf_l function", "ftscanf function", "fscanf_l function", "streams [C++], reading formatted data from", "_ftscanf function", "fwscanf_l function"] -ms.assetid: 9004e978-6c5f-4bb2-98fd-51e5948933f2 --- -# fscanf, _fscanf_l, fwscanf, _fwscanf_l +# `fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l` -Read formatted data from a stream. More secure versions of these functions are available; see [fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md). +Read formatted data from a stream. More secure versions of these functions are available; see [`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md). ## Syntax @@ -43,47 +42,47 @@ int _fwscanf_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to **`FILE`** structure. -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. ## Return Value -Each of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **EOF** for **fscanf** and **fwscanf**. +Each of these functions returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **`EOF`** for **`fscanf`** and **`fwscanf`**. -These functions validate their parameters. If *stream* or *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`stream`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EOF`** and set **`errno`** to **`EINVAL`**. ## Remarks -The **fscanf** function reads data from the current position of *stream* into the locations given by *argument* (if any). Each *argument* must be a pointer to a variable of a type that corresponds to a type specifier in *format*. *format* controls the interpretation of the input fields and has the same form and function as the *format* argument for **scanf**; see [scanf](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *format*. +The **`fscanf`** function reads data from the current position of *`stream`* into the locations given by *`argument`* (if any). Each *`argument`* must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for **`scanf`**; see [`scanf`](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *`format`*. -**fwscanf** is a wide-character version of **fscanf**; the format argument to **fwscanf** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **fscanf** doesn't currently support input from a UNICODE stream. +**`fwscanf`** is a wide-character version of **`fscanf`**; the format argument to **`fwscanf`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fscanf`** doesn't currently support input from a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. ### Generic-Text Routine Mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_ftscanf**|**fscanf**|**fscanf**|**fwscanf**| -|**_ftscanf_l**|**_fscanf_l**|**_fscanf_l**|**_fwscanf_l**| +|**`_ftscanf`**|**`fscanf`**|**`fscanf`**|**`fwscanf`**| +|**`_ftscanf_l`**|**`_fscanf_l`**|**`_fscanf_l`**|**`_fwscanf_l`**| -For more information, see [Format Specification Fields - scanf functions and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format Specification Fields - `scanf` functions and `wscanf` Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements |Function|Required header| |--------------|---------------------| -|**fscanf**, **_fscanf_l**|\| -|**fwscanf**, **_fwscanf_l**|\ or \| +|**`fscanf`**, **`_fscanf_l`**|``| +|**`fwscanf`**, **`_fwscanf_l`**|`` or ``| For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). @@ -148,9 +147,9 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
+[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md) diff --git a/docs/c-runtime-library/reference/fullpath-wfullpath.md b/docs/c-runtime-library/reference/fullpath-wfullpath.md index a5e57aaaf91..9ad1a84fec7 100644 --- a/docs/c-runtime-library/reference/fullpath-wfullpath.md +++ b/docs/c-runtime-library/reference/fullpath-wfullpath.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wfullpath", "fullpath", "_wfullpath", "_fullpath"] helpviewer_keywords: ["_wfullpath function", "relative file paths", "absolute paths", "wfullpath function", "_fullpath function", "fullpath function"] -ms.assetid: 4161ec17-0d22-45dd-b07d-0222553afae9 --- -# _fullpath, _wfullpath +# `_fullpath`, `_wfullpath` Creates an absolute or full path name for the specified relative path name. @@ -31,28 +30,26 @@ wchar_t *_wfullpath( ### Parameters -*absPath*
-Pointer to a buffer containing the absolute or full path name, or **NULL**. +*`absPath`*\ +Pointer to a buffer containing the absolute or full path name, or **`NULL`**. -*relPath*
+*`relPath`*\ Relative path name. -*maxLength*
-Maximum length of the absolute path name buffer (*absPath*). This length is in bytes for **_fullpath** but in wide characters (**`wchar_t`**) for **_wfullpath**. +*`maxLength`*\ +Maximum length of the absolute path name buffer (*`absPath`*). This length is in bytes for **`_fullpath`** but in wide characters (**`wchar_t`**) for **`_wfullpath`**. ## Return Value -Each of these functions returns a pointer to a buffer containing the absolute path name (*absPath*). If there is an error (for example, if the value passed in *relPath* includes a drive letter that is not valid or cannot be found, or if the length of the created absolute path name (*absPath*) is greater than *maxLength*), the function returns **NULL**. +Each of these functions returns a pointer to a buffer containing the absolute path name (*`absPath`*). If there's an error (for example, if the value passed in *`relPath`* includes a drive letter that isn't valid or can’t be found, or if the length of the created absolute path name (*`absPath`*) is greater than *`maxLength`*), the function returns **`NULL`**. ## Remarks -The **_fullpath** function expands the relative path name in *relPath* to its fully qualified or absolute path and stores this name in *absPath*. If *absPath* is **NULL**, **malloc** is used to allocate a buffer of sufficient length to hold the path name. It is the responsibility of the caller to free this buffer. A relative path name specifies a path to another location from the current location (such as the current working directory: "."). An absolute path name is the expansion of a relative path name that states the entire path required to reach the desired location from the root of the file system. Unlike **_makepath**, **_fullpath** can be used to obtain the absolute path name for relative paths (*relPath*) that include "./" or "../" in their names. +The **`_fullpath`** function expands the relative path name in *`relPath`* to its fully qualified or absolute path and stores this name in *`absPath`*. If *`absPath`* is **`NULL`**, **`malloc`** is used to allocate a buffer of sufficient length to hold the path name. It's the responsibility of the caller to free this buffer. A relative path name specifies a path to another location from the current location (such as the current working directory: `.`). An absolute path name is the expansion of a relative path name that states the entire path required to reach the desired location from the root of the file system. Unlike **`_makepath`**, **`_fullpath`** can be used to obtain the absolute path name for relative paths (*`relPath`*) that include `./` or `../` in their names. -For example, to use C run-time routines, the application must include the header files that contain the declarations for the routines. Each header file include statement references the location of the file in a relative manner (from the application's working directory): +For example, to use C run-time routines, the application must include the header files that contain the declarations for the routines. Each header file `#include` directive references the location of the file in a relative manner (from the application's working directory): ```C -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). - #include ``` @@ -60,26 +57,28 @@ when the absolute path (actual file system location) of the file might be: `\\machine\shareName\msvcSrc\crt\headerFiles\stdlib.h` -**_fullpath** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. **_wfullpath** is a wide-character version of **_fullpath**; the string arguments to **_wfullpath** are wide-character strings. **_wfullpath** and **_fullpath** behave identically except that **_wfullpath** does not handle multibyte-character strings. +By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). + +**`_fullpath`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. **`_wfullpath`** is a wide-character version of **`_fullpath`**; the string arguments to **`_wfullpath`** are wide-character strings. **`_wfullpath`** and **`_fullpath`** behave identically except that **`_wfullpath`** doesn't handle multibyte-character strings. -If **_DEBUG** and **_CRTDBG_MAP_ALLOC** are both defined, calls to **_fullpath** and **_wfullpath** are replaced by calls to **_fullpath_dbg** and **_wfullpath_dbg** to allow for debugging memory allocations. For more information, see [_fullpath_dbg, _wfullpath_dbg](fullpath-dbg-wfullpath-dbg.md). +If **`_DEBUG`** and **`_CRTDBG_MAP_ALLOC`** are both defined, calls to **`_fullpath`** and **`_wfullpath`** are replaced by calls to **`_fullpath_dbg`** and **`_wfullpath_dbg`** to allow for debugging memory allocations. For more information, see [`_fullpath_dbg`, `_wfullpath_dbg`](fullpath-dbg-wfullpath-dbg.md). -This function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), if *maxlen* is less than or equal to 0. If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **NULL**. +This function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), if *`maxlen`* is less than or equal to 0. If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns **`NULL`**. ### Generic-Text Routine Mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| +|`Tchar.h` routine|`_UNICODE and _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfullpath**|**_fullpath**|**_fullpath**|**_wfullpath**| +|**`_tfullpath`**|**`_fullpath`**|**`_fullpath`**|**`_wfullpath`**| -If the *absPath* buffer is **NULL**, **_fullpath** calls [malloc](malloc.md) to allocate a buffer and ignores the *maxLength* argument. It is the caller's responsibility to deallocate this buffer (using [free](free.md)) as appropriate. If the *relPath* argument specifies a disk drive, the current directory of this drive is combined with the path. +If the *`absPath`* buffer is **`NULL`**, **`_fullpath`** calls [`malloc`](malloc.md) to allocate a buffer and ignores the *`maxLength`* argument. It's the caller's responsibility to deallocate this buffer (using [`free`](free.md)) as appropriate. If the *`relPath`* argument specifies a disk drive, the current directory of this drive is combined with the path. ## Requirements |Function|Required header| |--------------|---------------------| -|**_fullpath**|\| -|**_wfullpath**|\ or \| +|**`_fullpath`**|``| +|**`_wfullpath`**|`` or ``| For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). @@ -120,8 +119,8 @@ Full path is: C:\Documents and Settings\user\test ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[_getdcwd, _wgetdcwd](getdcwd-wgetdcwd.md)
-[_makepath, _wmakepath](makepath-wmakepath.md)
-[_splitpath, _wsplitpath](splitpath-wsplitpath.md)
+[File Handling](../../c-runtime-library/file-handling.md)\ +[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md)\ +[`_makepath`, `_wmakepath`](makepath-wmakepath.md)\ +[`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md) diff --git a/docs/c-runtime-library/reference/srand.md b/docs/c-runtime-library/reference/srand.md index 12f40bdd2e0..38e05964878 100644 --- a/docs/c-runtime-library/reference/srand.md +++ b/docs/c-runtime-library/reference/srand.md @@ -9,9 +9,9 @@ topic_type: ["apiref"] f1_keywords: ["srand"] helpviewer_keywords: ["random starting point", "random starting point, setting", "random numbers, generating", "srand function", "numbers, pseudorandom", "numbers, random", "pseudorandom numbers", "starting points, setting random", "starting points"] --- -# srand +# `srand` -Sets the starting seed value for the pseudorandom number generator used by the **rand** function. +Sets the starting seed value for the pseudorandom number generator used by the **`rand`** function. ## Syntax @@ -23,12 +23,12 @@ void srand( ### Parameters -*seed*
+*`seed`*\ Seed for pseudorandom number generation ## Remarks -The **srand** function sets the starting point for generating a series of pseudorandom integers in the current thread. To reinitialize the generator to create the same sequence of results, call the **srand** function and use the same *seed* argument again. Any other value for *seed* sets the generator to a different starting point in the pseudorandom sequence. **rand** retrieves the pseudorandom numbers that are generated. Calling **rand** before any call to **srand** generates the same sequence as calling **srand** with *seed* passed as 1. +The **`srand`** function sets the starting point for generating a series of pseudorandom integers in the current thread. To reinitialize the generator to create the same sequence of results, call the **`srand`** function and use the same *`seed`* argument again. Any other value for *`seed`* sets the generator to a different starting point in the pseudorandom sequence. **`rand`** retrieves the pseudorandom numbers that are generated. Calling **`rand`** before any call to **`srand`** generates the same sequence as calling **`srand`** with *`seed`* passed as 1. By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). @@ -36,15 +36,15 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**srand**|\| +|**`srand`**|``| For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). ## Example -See the example for [rand](rand.md). +See the example for [`rand`](rand.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[rand](rand.md)
+[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[`rand`](rand.md) diff --git a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md index b152b519218..16c497a2c6f 100644 --- a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md +++ b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md @@ -9,9 +9,9 @@ topic_type: ["apiref"] f1_keywords: ["vstprintf", "vswprintf", "_vstprintf", "vsprintf", "__vswprintf_l", "_vsprintf_l", "_vswprintf_l", "vswprintf_l"] helpviewer_keywords: ["__vswprintf_l function", "_vstprintf_l function", "formatted text", "vstprintf_l function", "_vswprintf_l function", "vsprintf_l function", "buffers, avoiding overruns", "buffer overruns", "vswprintf_l function", "buffers, buffer overruns", "vstprintf function", "_vsprintf_l function", "vswprintf function", "vsprintf function", "_vstprintf function"] --- -# vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l +# `vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l` -Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see [vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md). +Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md). ## Syntax @@ -76,54 +76,54 @@ int _vswprintf_l( ### Parameters -*buffer*\ +*`buffer`*\ Storage location for output. -*count*\ +*`count`*\ Maximum number of characters to store, in the wide string versions of this function. -*format*\ +*`format`*\ Format specification. -*argptr*\ +*`argptr`*\ Pointer to list of arguments. -*locale*\ +*`locale`*\ The locale to use. ## Return Value -**vsprintf** and **vswprintf** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *buffer* or *format* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +**`vsprintf`** and **`vswprintf`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a `NULL` pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *buffer*. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *`buffer`*. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Using **vsprintf**, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [_vsnprintf](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [_vscprintf](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Using **`vsprintf`**, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [`_vsnprintf`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [`_vscprintf`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that *`format`* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -**vswprintf** conforms to the ISO C Standard, which requires the second parameter, *count*, of type **size_t**. To force the old nonstandard behavior, define **_CRT_NON_CONFORMING_SWPRINTFS**. The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. +**`vswprintf`** conforms to the ISO C Standard, which requires the second parameter, *`count`*, of type **`size_t`**. To force the old nonstandard behavior, define **`_CRT_NON_CONFORMING_SWPRINTFS`**. The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). ### Generic-Text Routine Mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| |---------------------|------------------------------------|--------------------|-----------------------| -|**_vstprintf**|**vsprintf**|**vsprintf**|**vswprintf**| -|**_vstprintf_l**|**_vsprintf_l**|**_vsprintf_l**|**_vswprintf_l**| +|**`_vstprintf`**|**`vsprintf`**|**`vsprintf`**|**`vswprintf`**| +|**`_vstprintf_l`**|**`_vsprintf_l`**|**`_vsprintf_l`**|**`_vswprintf_l`**| ## Requirements |Routine|Required header|Optional headers| |-------------|---------------------|----------------------| -|**vsprintf**, **_vsprintf_l**|\ and \|\*| -|**vswprintf**, **_vswprintf_l**|\ or \, and \|\*| +|**`vsprintf`**, **`_vsprintf_l`**|`` and ``|``*| +|**`vswprintf`**, **`_vswprintf_l`**|`` or ``, and ``|``*| \* Required for UNIX V compatibility. @@ -181,9 +181,9 @@ This is a string ## See also [Stream I/O](../../c-runtime-library/stream-i-o.md)\ -[vprintf Functions](../../c-runtime-library/vprintf-functions.md)\ -[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ -[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ -[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)\ -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ -[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md) +[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)\ +[Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `\__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md index 770089354d5..64e30476dec 100644 --- a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md +++ b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcstombs", "_wcstombs_l"] helpviewer_keywords: ["_wcstombs_l function", "wcstombs function", "string conversion, wide characters", "wide characters, converting", "wcstombs_l function", "characters, converting", "string conversion, multibyte character strings"] -ms.assetid: 91234252-9ea1-423a-af99-e9d0ce4a40e3 --- -# wcstombs, _wcstombs_l +# `wcstombs`, `_wcstombs_l` -Converts a sequence of wide characters to a corresponding sequence of multibyte characters. More secure versions of these functions are available; see [wcstombs_s, _wcstombs_s_l](wcstombs-s-wcstombs-s-l.md). +Converts a sequence of wide characters to a corresponding sequence of multibyte characters. More secure versions of these functions are available; see [`wcstombs_s`, `_wcstombs_s_l`](wcstombs-s-wcstombs-s-l.md). ## Syntax @@ -45,33 +44,33 @@ size_t _wcstombs_l( ### Parameters -*mbstr*
+*`mbstr`*\ The address of a sequence of multibyte characters. -*wcstr*
+*`wcstr`*\ The address of a sequence of wide characters. -*count*
+*`count`*\ The maximum number of bytes that can be stored in the multibyte output string. -*locale*
+*`locale`*\ The locale to use. ## Return Value -If **wcstombs** successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating null (if any). If the *mbstr* argument is **NULL**, **wcstombs** returns the required size in bytes of the destination string. If **wcstombs** encounters a wide character it cannot convert to a multibyte character, it returns -1 cast to type **size_t** and sets **errno** to **EILSEQ**. +If **`wcstombs`** successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating `NULL` (if any). If the *`mbstr`* argument is **`NULL`**, **`wcstombs`** returns the required size in bytes of the destination string. If **`wcstombs`** encounters a wide character it can’t convert to a multibyte character, it returns -1 cast to type **`size_t`** and sets **`errno`** to **`EILSEQ`**. ## Remarks -The **wcstombs** function converts the wide-character string pointed to by *wcstr* to the corresponding multibyte characters and stores the results in the *mbstr* array. The *count* parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of *mbstr*). In general, it is not known how many bytes will be required when converting a wide-character string. Some wide characters will require only one byte in the output string; others require two. If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character null), the result is guaranteed to fit. +The **`wcstombs`** function converts the wide-character string pointed to by *`wcstr`* to the corresponding multibyte characters and stores the results in the *`mbstr`* array. The *`count`* parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of *`mbstr`*). In general, it isn't known how many bytes will be required when converting a wide-character string. Some wide characters will require only one byte in the output string; others require two. If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character `NULL`), the result is guaranteed to fit. -If **wcstombs** encounters the wide-character null character (L'\0') either before or when *count* occurs, it converts it to an 8-bit 0 and stops. Thus, the multibyte character string at *mbstr* is null-terminated only if **wcstombs** encounters a wide-character null character during conversion. If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior of **wcstombs** is undefined. +If **`wcstombs`** encounters the wide-character `NULL` character (L'\0') either before or when *`count`* occurs, it converts it to an 8-bit 0 and stops. Thus, the multibyte character string at *`mbstr`* is `NULL` terminated only if **`wcstombs`** encounters a wide-character `NULL` character during conversion. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcstombs`** is undefined. -If the *mbstr* argument is **NULL**, **wcstombs** returns the required size in bytes of the destination string. +If the *`mbstr`* argument is **`NULL`**, **`wcstombs`** returns the required size in bytes of the destination string. -**wcstombs** validates its parameters. If *wcstr* is **NULL**, or if *count* is greater than **INT_MAX**, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function sets **errno** to **EINVAL** and returns -1. +**`wcstombs`** validates its parameters. If *`wcstr`* is **`NULL`**, or if *`count`* is greater than **`INT_MAX`**, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets **`errno`** to **`EINVAL`** and returns -1. -**wcstombs** uses the current locale for any locale-dependent behavior; **_wcstombs_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wcstombs`** uses the current locale for any locale-dependent behavior; **`_wcstombs_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). @@ -81,14 +80,14 @@ By default, this function's global state is scoped to the application. To change |Routine|Required header| |-------------|---------------------| -|**wcstombs**|\| -|**_wcstombs_l**|\| +|**`wcstombs`**|``| +|**`_wcstombs_l`**|``| For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). ## Example -This program illustrates the behavior of the **wcstombs** function. +This program illustrates the behavior of the **`wcstombs`** function. ```C // crt_wcstombs.c @@ -130,10 +129,10 @@ Convert wide-character string: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data Conversion](../../c-runtime-library/data-conversion.md)\ +[Locale](../../c-runtime-library/locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/mfc/reference/cpropertypage-class.md b/docs/mfc/reference/cpropertypage-class.md index 17f516ce483..8b2c9507064 100644 --- a/docs/mfc/reference/cpropertypage-class.md +++ b/docs/mfc/reference/cpropertypage-class.md @@ -4,9 +4,8 @@ title: "CPropertyPage Class" ms.date: "11/04/2016" f1_keywords: ["CPropertyPage", "AFXDLGS/CPropertyPage", "AFXDLGS/CPropertyPage::CPropertyPage", "AFXDLGS/CPropertyPage::CancelToClose", "AFXDLGS/CPropertyPage::Construct", "AFXDLGS/CPropertyPage::GetPSP", "AFXDLGS/CPropertyPage::OnApply", "AFXDLGS/CPropertyPage::OnCancel", "AFXDLGS/CPropertyPage::OnKillActive", "AFXDLGS/CPropertyPage::OnOK", "AFXDLGS/CPropertyPage::OnQueryCancel", "AFXDLGS/CPropertyPage::OnReset", "AFXDLGS/CPropertyPage::OnSetActive", "AFXDLGS/CPropertyPage::OnWizardBack", "AFXDLGS/CPropertyPage::OnWizardFinish", "AFXDLGS/CPropertyPage::OnWizardNext", "AFXDLGS/CPropertyPage::QuerySiblings", "AFXDLGS/CPropertyPage::SetModified", "AFXDLGS/CPropertyPage::m_psp"] helpviewer_keywords: ["CPropertyPage [MFC], CPropertyPage", "CPropertyPage [MFC], CancelToClose", "CPropertyPage [MFC], Construct", "CPropertyPage [MFC], GetPSP", "CPropertyPage [MFC], OnApply", "CPropertyPage [MFC], OnCancel", "CPropertyPage [MFC], OnKillActive", "CPropertyPage [MFC], OnOK", "CPropertyPage [MFC], OnQueryCancel", "CPropertyPage [MFC], OnReset", "CPropertyPage [MFC], OnSetActive", "CPropertyPage [MFC], OnWizardBack", "CPropertyPage [MFC], OnWizardFinish", "CPropertyPage [MFC], OnWizardNext", "CPropertyPage [MFC], QuerySiblings", "CPropertyPage [MFC], SetModified", "CPropertyPage [MFC], m_psp"] -ms.assetid: d9000a21-aa81-4530-85d9-f43432afb4dc --- -# CPropertyPage Class +# `CPropertyPage` Class Represents individual pages of a property sheet, otherwise known as a tab dialog box. @@ -22,59 +21,59 @@ class CPropertyPage : public CDialog |Name|Description| |----------|-----------------| -|[CPropertyPage::CPropertyPage](#cpropertypage)|Constructs a `CPropertyPage` object.| +|[`CPropertyPage::CPropertyPage`](#cpropertypage)|Constructs a `CPropertyPage` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CPropertyPage::CancelToClose](#canceltoclose)|Changes the OK button to read Close, and disables the Cancel button, after an unrecoverable change in the page of a modal property sheet.| -|[CPropertyPage::Construct](#construct)|Constructs a `CPropertyPage` object. Use `Construct` if you want to specify your parameters at run time, or if you are using arrays.| -|[CPropertyPage::GetPSP](#getpsp)|Retrieves the Windows [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object.| -|[CPropertyPage::OnApply](#onapply)|Called by the framework when the Apply Now button is clicked.| -|[CPropertyPage::OnCancel](#oncancel)|Called by the framework when the Cancel button is clicked.| -|[CPropertyPage::OnKillActive](#onkillactive)|Called by the framework when the current page is no longer the active page. Perform data validation here.| -|[CPropertyPage::OnOK](#onok)|Called by the framework when the OK, Apply Now, or Close button is clicked.| -|[CPropertyPage::OnQueryCancel](#onquerycancel)|Called by the framework when the Cancel button is clicked, and before the cancel has taken place.| -|[CPropertyPage::OnReset](#onreset)|Called by the framework when the Cancel button is clicked.| -|[CPropertyPage::OnSetActive](#onsetactive)|Called by the framework when the page is made the active page.| -|[CPropertyPage::OnWizardBack](#onwizardback)|Called by the framework when the Back button is clicked while using a wizard-type property sheet.| -|[CPropertyPage::OnWizardFinish](#onwizardfinish)|Called by the framework when the Finish button is clicked while using a wizard-type property sheet.| -|[CPropertyPage::OnWizardNext](#onwizardnext)|Called by the framework when the Next button is clicked while using a wizard-type property sheet.| -|[CPropertyPage::QuerySiblings](#querysiblings)|Forwards the message to each page of the property sheet.| -|[CPropertyPage::SetModified](#setmodified)|Call to activate or deactivate the Apply Now button.| +|[`CPropertyPage::CancelToClose`](#canceltoclose)|Changes the **OK** button to read **Close**, and disables the **Cancel** button, after an unrecoverable change in the page of a modal property sheet.| +|[`CPropertyPage::Construct`](#construct)|Constructs a `CPropertyPage` object. Use `Construct` if you want to specify your parameters at run time, or if you're using arrays.| +|[`CPropertyPage::GetPSP`](#getpsp)|Retrieves the Windows [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object.| +|[`CPropertyPage::OnApply`](#onapply)|Called by the framework when the **Apply Now** button is clicked.| +|[`CPropertyPage::OnCancel`](#oncancel)|Called by the framework when the **Cancel** button is clicked.| +|[`CPropertyPage::OnKillActive`](#onkillactive)|Called by the framework when the current page is no longer the active page. Perform data validation here.| +|[`CPropertyPage::OnOK`](#onok)|Called by the framework when the **OK**, **Apply Now**, or **Close** button is clicked.| +|[`CPropertyPage::OnQueryCancel`](#onquerycancel)|Called by the framework when the **Cancel** button is clicked, and before the cancel has taken place.| +|[`CPropertyPage::OnReset`](#onreset)|Called by the framework when the **Cancel** button is clicked.| +|[`CPropertyPage::OnSetActive`](#onsetactive)|Called by the framework when the page is made the active page.| +|[`CPropertyPage::OnWizardBack`](#onwizardback)|Called by the framework when the **Back** button is clicked while using a wizard-type property sheet.| +|[`CPropertyPage::OnWizardFinish`](#onwizardfinish)|Called by the framework when the **Finish** button is clicked while using a wizard-type property sheet.| +|[`CPropertyPage::OnWizardNext`](#onwizardnext)|Called by the framework when the **Next** button is clicked while using a wizard-type property sheet.| +|[`CPropertyPage::QuerySiblings`](#querysiblings)|Forwards the message to each page of the property sheet.| +|[`CPropertyPage::SetModified`](#setmodified)|Call to activate or deactivate the **Apply Now** button.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CPropertyPage::m_psp](#m_psp)|The Windows [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure. Provides access to basic property page parameters.| +|[`CPropertyPage::m_psp`](#m_psp)|The Windows [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure. Provides access to basic property page parameters.| ## Remarks -As with standard dialog boxes, you derive a class from `CPropertyPage` for each page in your property sheet. To use `CPropertyPage`-derived objects, first create a [CPropertySheet](../../mfc/reference/cpropertysheet-class.md) object, and then create an object for each page that goes in the property sheet. Call [CPropertySheet::AddPage](../../mfc/reference/cpropertysheet-class.md#addpage) for each page in the sheet, and then display the property sheet by calling [CPropertySheet::DoModal](../../mfc/reference/cpropertysheet-class.md#domodal) for a modal property sheet, or [CPropertySheet::Create](../../mfc/reference/cpropertysheet-class.md#create) for a modeless property sheet. +As with standard dialog boxes, you derive a class from `CPropertyPage` for each page in your property sheet. To use `CPropertyPage`-derived objects, first create a [`CPropertySheet`](../../mfc/reference/cpropertysheet-class.md) object, and then create an object for each page that goes in the property sheet. Call [`CPropertySheet::AddPage`](../../mfc/reference/cpropertysheet-class.md#addpage) for each page in the sheet, and then display the property sheet by calling [`CPropertySheet::DoModal`](../../mfc/reference/cpropertysheet-class.md#domodal) for a modal property sheet, or [`CPropertySheet::Create`](../../mfc/reference/cpropertysheet-class.md#create) for a modeless property sheet. -You can create a type of tab dialog box called a wizard, which consists of a property sheet with a sequence of property pages that guide the user through the steps of an operation, such as setting up a device or creating a newsletter. In a wizard-type tab dialog box, the property pages do not have tabs, and only one property page is visible at a time. Also, instead of having OK and Apply Now buttons, a wizard-type tab dialog box has a Back button, a Next or Finish button, and a Cancel button. +You can create a type of tab dialog box called a wizard, which consists of a property sheet with a sequence of property pages that guide the user through the steps of an operation, such as setting up a device or creating a newsletter. In a wizard-type tab dialog box, the property pages don't have tabs, and only one property page is visible at a time. Also, instead of having **OK** and **Apply Now** buttons, a wizard-type tab dialog box has a **Back** button, a **Next** or **Finish** button, and a **Cancel** button. -For more information on establishing a property sheet as a wizard, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). For more information on using `CPropertyPage` objects, see the article [Property Sheets and Property Pages](../../mfc/property-sheets-and-property-pages-in-mfc.md). +For more information on establishing a property sheet as a wizard, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). For more information on using `CPropertyPage` objects, see the article [Property Sheets and Property Pages](../../mfc/property-sheets-and-property-pages-in-mfc.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CDialog](../../mfc/reference/cdialog-class.md) +[`CDialog`](../../mfc/reference/cdialog-class.md) `CPropertyPage` ## Requirements -**Header:** afxdlgs.h +**Header:** `afxdlgs.h` -## CPropertyPage::CancelToClose +## `CPropertyPage::CancelToClose` Call this function after an unrecoverable change has been made to the data in a page of a modal property sheet. @@ -84,15 +83,15 @@ void CancelToClose(); ### Remarks -This function will change the OK button to Close and disable the Cancel button. This change alerts the user that a change is permanent and the modifications cannot be cancelled. +This function will change the **OK** button to **Close** and disable the **Cancel** button. This change alerts the user that a change is permanent and the modifications can’t be canceled. -The `CancelToClose` member function does nothing in a modeless property sheet, because a modeless property sheet does not have a Cancel button by default. +The `CancelToClose` member function does nothing in a modeless property sheet, because a modeless property sheet doesn't have a **Cancel** button by default. ### Example See the example for [CPropertyPage::QuerySiblings](#querysiblings). -## CPropertyPage::Construct +## `CPropertyPage::Construct` Call this member function to construct a `CPropertyPage` object. @@ -120,32 +119,32 @@ void Construct( ### Parameters -*nIDTemplate*
+*`nIDTemplate`*\ ID of the template used for this page. -*nIDCaption*
+*`nIDCaption`*\ ID of the name to be placed in the tab for this page. If 0, the name will be taken from the dialog template for this page. -*lpszTemplateName*
+*`lpszTemplateName`*\ Contains a null-terminated string that is the name of a template resource. -*nIDHeaderTitle*
+*`nIDHeaderTitle`*\ ID of the name to be placed in the title location of the property page header. By default, 0. -*nIDHeaderSubTitle*
+*`nIDHeaderSubTitle`*\ ID of the name to be placed in the subtitle location of the property page header. By default, 0. ### Remarks The object is displayed after all of the following conditions are met: -- The page has been added to a property sheet using [CPropertySheet::AddPage](../../mfc/reference/cpropertysheet-class.md#addpage). +- The page has been added to a property sheet using [`CPropertySheet::AddPage`](../../mfc/reference/cpropertysheet-class.md#addpage). -- The property sheet's [DoModal](../../mfc/reference/cpropertysheet-class.md#domodal) or [Create](../../mfc/reference/cpropertysheet-class.md#create) function has been called. +- The property sheet's [`DoModal`](../../mfc/reference/cpropertysheet-class.md#domodal) or [`Create`](../../mfc/reference/cpropertysheet-class.md#create) function has been called. - The user has selected (tabbed to) this page. -Call `Construct` if one of the other class constructors has not been called. The `Construct` member function is flexible because you can leave the parameter statement blank and then specify multiple parameters and construction at any point in your code. +Call `Construct` if one of the other class constructors hasn't been called. The `Construct` member function is flexible because you can leave the parameter statement blank and then specify multiple parameters and construction at any point in your code. You must use `Construct` when you work with arrays, and you must call `Construct` for each member of the array so that the data members are assigned proper values. @@ -153,7 +152,7 @@ You must use `Construct` when you work with arrays, and you must call `Construct [!code-cpp[NVC_MFCDocView#112](../../mfc/codesnippet/cpp/cpropertypage-class_1.cpp)] -## CPropertyPage::CPropertyPage +## `CPropertyPage::CPropertyPage` Constructs a `CPropertyPage` object. @@ -187,41 +186,41 @@ CPropertyPage( ### Parameters -*nIDTemplate*
+*`nIDTemplate`*\ ID of the template used for this page. -*nIDCaption*
+*`nIDCaption`*\ ID of the name to be placed in the tab for this page. If 0, the name will be taken from the dialog template for this page. -*dwSize*
-*lpszTemplateName* -Points to a string containing the name of the template for this page. Cannot be NULL. +*`dwSize`*\ +*`lpszTemplateName`* +Points to a string containing the name of the template for this page. Can’t be `NULL`. -*nIDHeaderTitle*
+*`nIDHeaderTitle`*\ ID of the name to be placed in the title location of the property page header. -*nIDHeaderSubTitle*
+*`nIDHeaderSubTitle`*\ ID of the name to be placed in the subtitle location of the property page header. ### Remarks The object is displayed after all of the following conditions are met: -- The page has been added to a property sheet using [CPropertySheet::AddPage](../../mfc/reference/cpropertysheet-class.md#addpage). +- The page has been added to a property sheet using [`CPropertySheet::AddPage`](../../mfc/reference/cpropertysheet-class.md#addpage). -- The property sheet's [DoModal](../../mfc/reference/cpropertysheet-class.md#domodal) or [Create](../../mfc/reference/cpropertysheet-class.md#create) function has been called. +- The property sheet's [`DoModal`](../../mfc/reference/cpropertysheet-class.md#domodal) or [`Create`](../../mfc/reference/cpropertysheet-class.md#create) function has been called. - The user has selected (tabbed to) this page. -If you have multiple parameters (for example, if you are using an array), use [CPropertySheet::Construct](../../mfc/reference/cpropertysheet-class.md#construct) instead of `CPropertyPage`. +If you have multiple parameters (for example, if you're using an array), use [`CPropertySheet::Construct`](../../mfc/reference/cpropertysheet-class.md#construct) instead of `CPropertyPage`. ### Example [!code-cpp[NVC_MFCDocView#113](../../mfc/codesnippet/cpp/cpropertypage-class_2.cpp)] -## CPropertyPage::GetPSP +## `CPropertyPage::GetPSP` -Retrieves the Windows [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object. +Retrieves the Windows [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object. ``` const PROPSHEETPAGE& GetPSP() const; @@ -233,9 +232,9 @@ PROPSHEETPAGE& GetPSP(); A reference to the `PROPSHEETPAGE` structure. -## CPropertyPage::m_psp +## `CPropertyPage::m_psp` -`m_psp` is a structure whose members store the characteristics of [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2). +`m_psp` is a structure whose members store the characteristics of [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2). ``` PROPSHEETPAGE m_psp; @@ -243,7 +242,7 @@ PROPSHEETPAGE m_psp; ### Remarks -Use this structure to initialize the appearance of a property page after it is constructed. +Use this structure to initialize the appearance of a property page after it's constructed. For more information on this structure, including a listing of its members, see `PROPSHEETPAGE` in the Windows SDK. @@ -251,9 +250,9 @@ For more information on this structure, including a listing of its members, see [!code-cpp[NVC_MFCDocView#128](../../mfc/codesnippet/cpp/cpropertypage-class_3.cpp)] -## CPropertyPage::OnApply +## `CPropertyPage::OnApply` -This member function is called by the framework when the user chooses the OK or the Apply Now button. +This member function is called by the framework when the user chooses the **OK** or the **Apply Now** button. ``` virtual BOOL OnApply(); @@ -265,21 +264,21 @@ Nonzero if the changes are accepted; otherwise 0. ### Remarks -When the framework calls this function, changes made on all property pages in the property sheet are accepted, the property sheet retains focus, and `OnApply` returns TRUE (the value 1). Before `OnApply` can be called by the framework, you must have called [SetModified](#setmodified) and set its parameter to TRUE. This will activate the Apply Now button as soon as the user makes a change on the property page. +When the framework calls this function, changes made on all property pages in the property sheet are accepted, the property sheet retains focus, and `OnApply` returns `TRUE` (the value 1). Before `OnApply` can be called by the framework, you must have called [`SetModified`](#setmodified) and set its parameter to `TRUE`. This will activate the **Apply Now** button as soon as the user makes a change on the property page. -Override this member function to specify what action your program takes when the user clicks the Apply Now button. When overriding, the function should return TRUE to accept changes and FALSE to prevent changes from taking effect. +Override this member function to specify what action your program takes when the user selects the **Apply Now** button. When overriding, the function should return `TRUE` to accept changes and `FALSE` to prevent changes from taking effect. The default implementation of `OnApply` calls `OnOK`. -For more information about notification messages sent when the user presses the Apply Now or OK button in a property sheet, see [PSN_APPLY](/windows/win32/Controls/psn-apply) in the Windows SDK. +For more information about notification messages sent when the user presses the **Apply Now** or **OK** button in a property sheet, see [`PSN_APPLY`](/windows/win32/Controls/psn-apply) in the Windows SDK. ### Example See the example for [CPropertyPage::OnOK](#onok). -## CPropertyPage::OnCancel +## `CPropertyPage::OnCancel` -This member function is called by the framework when the Cancel button is selected. +This member function is called by the framework when the **Cancel** button is selected. ``` virtual void OnCancel(); @@ -287,13 +286,13 @@ virtual void OnCancel(); ### Remarks -Override this member function to perform Cancel button actions. The default negates any changes that have been made. +Override this member function to perform **Cancel** button actions. The default negates any changes that have been made. ### Example [!code-cpp[NVC_MFCDocView#114](../../mfc/codesnippet/cpp/cpropertypage-class_4.cpp)] -## CPropertyPage::OnKillActive +## `CPropertyPage::OnKillActive` This member function is called by the framework when the page is no longer the active page. @@ -309,17 +308,17 @@ Nonzero if data was updated successfully, otherwise 0. Override this member function to perform special data validation tasks. -The default implementation of this member function copies settings from the controls in the property page to the member variables of the property page. If the data was not updated successfully due to a dialog data validation (DDV) error, the page retains focus. +The default implementation of this member function copies settings from the controls in the property page to the member variables of the property page. If the data wasn't updated successfully due to a dialog data validation (DDV) error, the page retains focus. -After this member function returns successfully, the framework will call the page's [OnOK](#onok) function. +After this member function returns successfully, the framework will call the page's [`OnOK`](#onok) function. ### Example [!code-cpp[NVC_MFCDocView#115](../../mfc/codesnippet/cpp/cpropertypage-class_5.cpp)] -## CPropertyPage::OnOK +## `CPropertyPage::OnOK` -This member function is called by the framework when the user chooses either the OK or the Apply Now button, immediately after the framework calls [OnKillActive](#onkillactive). +This member function is called by the framework when the user chooses either the **OK** or the **Apply Now** button, immediately after the framework calls [`OnKillActive`](#onkillactive). ``` virtual void OnOK(); @@ -327,7 +326,7 @@ virtual void OnOK(); ### Remarks -When the user chooses either the OK or the Apply Now button, the framework receives the [PSN_APPLY](/windows/win32/Controls/psn-apply) notification from the property page. The call to `OnOK` won't be made if you call [CPropertySheet::PressButton](../../mfc/reference/cpropertysheet-class.md#pressbutton) because the property page does not send the notification in that case. +When the user chooses either the **OK** or the **Apply Now** button, the framework receives the [`PSN_APPLY`](/windows/win32/Controls/psn-apply) notification from the property page. The call to `OnOK` won't be made if you call [`CPropertySheet::PressButton`](../../mfc/reference/cpropertysheet-class.md#pressbutton) because the property page doesn't send the notification in that case. Override this member function to implement additional behavior specific to the currently active page when user dismisses the entire property sheet. @@ -337,9 +336,9 @@ The default implementation of this member function marks the page as "clean" to [!code-cpp[NVC_MFCDocView#116](../../mfc/codesnippet/cpp/cpropertypage-class_6.cpp)] -## CPropertyPage::OnQueryCancel +## `CPropertyPage::OnQueryCancel` -This member function is called by the framework when the user clicks the Cancel button and before the cancel action has taken place. +This member function is called by the framework when the user selects the **Cancel** button and before the cancel action has taken place. ``` virtual BOOL OnQueryCancel(); @@ -347,21 +346,21 @@ virtual BOOL OnQueryCancel(); ### Return Value -Returns FALSE to prevent the cancel operation or TRUE to allow it. +Returns `FALSE` to prevent the cancel operation or `TRUE` to allow it. ### Remarks -Override this member function to specify an action the program takes when the user clicks the Cancel button. +Override this member function to specify an action the program takes when the user selects the **Cancel** button. -The default implementation of `OnQueryCancel` returns TRUE. +The default implementation of `OnQueryCancel` returns `TRUE`. ### Example [!code-cpp[NVC_MFCDocView#117](../../mfc/codesnippet/cpp/cpropertypage-class_7.cpp)] -## CPropertyPage::OnReset +## `CPropertyPage::OnReset` -This member function is called by the framework when the user chooses the Cancel button. +This member function is called by the framework when the user chooses the **Cancel** button. ``` virtual void OnReset(); @@ -369,9 +368,9 @@ virtual void OnReset(); ### Remarks -When the framework calls this function, changes to all property pages that were made by the user previously choosing the Apply Now button are discarded, and the property sheet retains focus. +When the framework calls this function, changes to all property pages that were made by the user previously choosing the **Apply Now** button are discarded, and the property sheet retains focus. -Override this member function to specify what action the program takes when the user clicks the Cancel button. +Override this member function to specify what action the program takes when the user selects the **Cancel** button. The default implementation of `OnReset` does nothing. @@ -379,7 +378,7 @@ The default implementation of `OnReset` does nothing. See the example for [CPropertyPage::OnCancel](#oncancel). -## CPropertyPage::OnSetActive +## `CPropertyPage::OnSetActive` This member function is called by the framework when the page is chosen by the user and becomes the active page. @@ -401,9 +400,9 @@ The default implementation creates the window for the page, if not previously cr See the example for [CPropertySheet::SetFinishText](../../mfc/reference/cpropertysheet-class.md#setfinishtext). -## CPropertyPage::OnWizardBack +## `CPropertyPage::OnWizardBack` -This member function is called by the framework when the user clicks on the Back button in a wizard. +This member function is called by the framework when the user selects the **Back** button in a wizard. ``` virtual LRESULT OnWizardBack(); @@ -415,17 +414,17 @@ virtual LRESULT OnWizardBack(); ### Remarks -Override this member function to specify some action the user must take when the Back button is pressed. +Override this member function to specify some action the user must take when the **Back** button is pressed. -For more information on how to make a wizard-type property sheet, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). +For more information on how to make a wizard-type property sheet, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). ### Example [!code-cpp[NVC_MFCDocView#118](../../mfc/codesnippet/cpp/cpropertypage-class_8.cpp)] -## CPropertyPage::OnWizardFinish +## `CPropertyPage::OnWizardFinish` -This member function is called by the framework when the user clicks on the Finish button in a wizard. +This member function is called by the framework when the user selects the **Finish** button in a wizard. ``` virtual BOOL OnWizardFinish(); @@ -437,13 +436,13 @@ Nonzero if the property sheet is destroyed when the wizard finishes; otherwise z ### Remarks -When a user clicks the **Finish** button in a wizard, the framework calls this function; when `OnWizardFinish` returns TRUE (a nonzero value), the property sheet is able to be destroyed (but is not actually destroyed). Call `DestroyWindow` to destroy the property sheet. Do not call `DestroyWindow` from `OnWizardFinish`; doing so will cause heap corruption or other errors. +When a user selects the **Finish** button in a wizard, the framework calls this function; when `OnWizardFinish` returns `TRUE` (a nonzero value), the property sheet is able to be destroyed (but isn't actually destroyed). Call `DestroyWindow` to destroy the property sheet. Don't call `DestroyWindow` from `OnWizardFinish`; doing so will cause heap corruption or other errors. -You can override this member function to specify some action the user must take when the Finish button is pressed. When overriding this function, return FALSE to prevent the property sheet from being destroyed. +You can override this member function to specify some action the user must take when the **Finish** button is pressed. When overriding this function, return `FALSE` to prevent the property sheet from being destroyed. -For more information about notification messages sent when the user presses the Finish button in a wizard property sheet, see [PSN_WIZFINISH](/windows/win32/Controls/psn-wizfinish) in the Windows SDK. +For more information about notification messages sent when the user presses the **Finish** button in a wizard property sheet, see [`PSN_WIZFINISH`](/windows/win32/Controls/psn-wizfinish) in the Windows SDK. -For more information on how to make a wizard-type property sheet, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). +For more information on how to make a wizard-type property sheet, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). ### Example @@ -455,9 +454,9 @@ For more information on how to make a wizard-type property sheet, see [CProperty [!code-cpp[NVC_MFCDocView#122](../../mfc/codesnippet/cpp/cpropertypage-class_12.cpp)] -## CPropertyPage::OnWizardNext +## `CPropertyPage::OnWizardNext` -This member function is called by the framework when the user clicks on the Next button in a wizard. +This member function is called by the framework when the user selects the **Next** button in a wizard. ``` virtual LRESULT OnWizardNext(); @@ -469,15 +468,15 @@ virtual LRESULT OnWizardNext(); ### Remarks -Override this member function to specify some action the user must take when the Next button is pressed. +Override this member function to specify some action the user must take when the **Next** button is pressed. -For more information on how to make a wizard-type property sheet, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). +For more information on how to make a wizard-type property sheet, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). ### Example [!code-cpp[NVC_MFCDocView#123](../../mfc/codesnippet/cpp/cpropertypage-class_13.cpp)] -## CPropertyPage::QuerySiblings +## `CPropertyPage::QuerySiblings` Call this member function to forward a message to each page in the property sheet. @@ -489,10 +488,10 @@ LRESULT QuerySiblings( ### Parameters -*wParam*
+*`wParam`*\ Specifies additional message-dependent information. -*lParam*
+*`lParam`*\ Specifies additional message-dependent information ### Return Value @@ -501,7 +500,7 @@ The nonzero value from a page in the property sheet, or 0 if all pages return a ### Remarks -If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. +If a page returns a nonzero value, the property sheet doesn't send the message to subsequent pages. ### Example @@ -511,9 +510,9 @@ If a page returns a nonzero value, the property sheet does not send the message [!code-cpp[NVC_MFCDocView#126](../../mfc/codesnippet/cpp/cpropertypage-class_16.cpp)] -## CPropertyPage::SetModified +## `CPropertyPage::SetModified` -Call this member function to enable or disable the Apply Now button, based on whether the settings in the property page should be applied to the appropriate external object. +Call this member function to enable or disable the **Apply Now** button, based on whether the settings in the property page should be applied to the appropriate external object. ```cpp void SetModified(BOOL bChanged = TRUE); @@ -521,12 +520,12 @@ void SetModified(BOOL bChanged = TRUE); ### Parameters -*bChanged*
-TRUE to indicate that the property page settings have been modified since the last time they were applied; FALSE to indicate that the property page settings have been applied, or should be ignored. +*`bChanged`*\ +`TRUE` to indicate that the property page settings have been modified since the last time they were applied; `FALSE` to indicate that the property page settings have been applied, or should be ignored. ### Remarks -The framework keeps track of which pages are "dirty," that is, property pages for which you have called `SetModified( TRUE )`. The Apply Now button will always be enabled if you call `SetModified( TRUE )` for one of the pages. The Apply Now button will be disabled when you call `SetModified( FALSE )` for one of the pages, but only if none of the other pages is "dirty." +The framework keeps track of which pages are "dirty," that is, property pages for which you have called `SetModified( TRUE )`. The **Apply Now** button will always be enabled if you call `SetModified( TRUE )` for one of the pages. The **Apply Now** button will be disabled when you call `SetModified( FALSE )` for one of the pages, but only if none of the other pages is "dirty." ### Example @@ -534,11 +533,10 @@ The framework keeps track of which pages are "dirty," that is, property pages fo ## See also -[MFC Sample CMNCTRL1](../../overview/visual-cpp-samples.md)
-[MFC Sample CMNCTRL2](../../overview/visual-cpp-samples.md)
-[MFC Sample PROPDLG](../../overview/visual-cpp-samples.md)
-[MFC Sample SNAPVW](../../overview/visual-cpp-samples.md)
-[CDialog Class](../../mfc/reference/cdialog-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CPropertySheet Class](../../mfc/reference/cpropertysheet-class.md)
-[CDialog Class](../../mfc/reference/cdialog-class.md) +[MFC Sample `CMNCTRL1`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `CMNCTRL2`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `PROPDLG`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `SNAPVW`](../../overview/visual-cpp-samples.md)\ +[`CDialog` Class](../../mfc/reference/cdialog-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CPropertySheet` Class](../../mfc/reference/cpropertysheet-class.md) diff --git a/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md b/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md index b22221af984..40010ce0635 100644 --- a/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md +++ b/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md @@ -4,11 +4,10 @@ title: "Creating a Web Browser-Style MFC Application" ms.date: "06/25/2018" f1_keywords: ["vc.appwiz.mfcweb.project"] helpviewer_keywords: ["MFC, Web applications", "Web browsers, creating from MFC architecture", "Web browsers", "Web applications [MFC], creating"] -ms.assetid: 257f8c03-33c3-428c-832e-0b70aff6168d --- # Creating a Web Browser-Style MFC Application -A Web browser-style application can access information from the Internet (such as HTML or active documents) or an intranet, as well as folders in the local file system and on a network. By deriving the application's view class from [CHtmlView](../../mfc/reference/chtmlview-class.md), effectively you make the application a Web browser by providing the view with the WebBrowser control. +A Web browser-style application can access information from the Internet (such as HTML or active documents) or an intranet, as well as folders in the local file system and on a network. By deriving the application's view class from [`CHtmlView`](../../mfc/reference/chtmlview-class.md), effectively you make the application a Web browser by providing the view with the WebBrowser control. ## To create a Web browser application based on the MFC document/view architecture @@ -20,16 +19,16 @@ A Web browser-style application can access information from the Internet (such a 1. Select any other options you want built into the skeleton application. -1. Click **Finish**. +1. Select **Finish**. The WebBrowser control supports Web browsing through hyperlinks and Uniform Resource Locator (URL) navigation. The control maintains a history list that allows the user to browse forward and backward through previously browsed sites, folders, and documents. The control directly handles the navigation, hyperlinks, history lists, favorites, and security. Applications can use the WebBrowser control as an active document container to host active documents as well. Thus, richly formatted documents such as Microsoft Excel spreadsheets or Word documents can be opened and edited in place from within the WebBrowser control. The WebBrowser control is also an ActiveX control container that can host any ActiveX control. > [!NOTE] > The WebBrowser ActiveX control (and therefore `CHtmlView`) is available only to applications running under Windows versions in which Internet Explorer 4.0 or later has been installed. -Because `CHtmlView` simply implements the Microsoft Web browser control, its support for printing is not like other [CView](../../mfc/reference/cview-class.md)-derived classes. Rather, the WebBrowser control implements the printer user interface and printing. As a result, `CHtmlView` does not support print preview, and the framework does not provide for other printing support functions: for example, [CView::OnPreparePrinting](../../mfc/reference/cview-class.md#onprepareprinting), [CView::OnBeginPrinting](../../mfc/reference/cview-class.md#onbeginprinting), and [CView::OnEndPrinting](../../mfc/reference/cview-class.md#onendprinting), which are available in other MFC applications. +Because `CHtmlView` simply implements the Microsoft Web browser control, its support for printing isn't like other [`CView`](../../mfc/reference/cview-class.md)-derived classes. Rather, the WebBrowser control implements the printer user interface and printing. As a result, `CHtmlView` doesn't support print preview, and the framework doesn't provide for other printing support functions: for example, [`CView::OnPreparePrinting`](../../mfc/reference/cview-class.md#onprepareprinting), [`CView::OnBeginPrinting`](../../mfc/reference/cview-class.md#onbeginprinting), and [`CView::OnEndPrinting`](../../mfc/reference/cview-class.md#onendprinting), which are available in other MFC applications. -`CHtmlView` acts as a wrapper for the Web browser control, which gives your application a view onto a Web or an HTML page. The wizard creates an override to the [OnInitialUpdate](../../mfc/reference/cview-class.md#oninitialupdate) function in the view class, providing a navigational link to the Microsoft Visual C++ Web site: +`CHtmlView` acts as a wrapper for the Web browser control, which gives your application a view onto a Web or an HTML page. The wizard creates an override to the [`OnInitialUpdate`](../../mfc/reference/cview-class.md#oninitialupdate) function in the view class, providing a navigational link to the Microsoft Visual C++ Web site: ```cpp void CWebView::OnInitialUpdate() @@ -44,7 +43,7 @@ void CWebView::OnInitialUpdate() } ``` -You can replace this site with one of your own, or you can use the [LoadFromResource](../../mfc/reference/chtmlview-class.md#loadfromresource) member function to open an HTML page that resides in the project's resource script as the default content for the view. For example: +You can replace this site with one of your own, or you can use the [`LoadFromResource`](../../mfc/reference/chtmlview-class.md#loadfromresource) member function to open an HTML page that resides in the project's resource script as the default content for the view. For example: ```cpp void CWebView::OnInitialUpdate() @@ -59,8 +58,8 @@ void CWebView::OnInitialUpdate() ## See also -[MFC Sample MFCIE](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet)
-[MFC Application Wizard](../../mfc/reference/mfc-application-wizard.md)
-[Set compiler and build properties](../../build/working-with-project-properties.md)
-[Property Pages](../../build/reference/property-pages-visual-cpp.md)
+[MFC Sample MFCIE](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet)\ +[MFC Application Wizard](../../mfc/reference/mfc-application-wizard.md)\ +[Set compiler and build properties](../../build/working-with-project-properties.md)\ +[Property Pages](../../build/reference/property-pages-visual-cpp.md)\ [Set compiler and build properties](../../build/working-with-project-properties.md) diff --git a/docs/mfc/reference/csinglelock-class.md b/docs/mfc/reference/csinglelock-class.md index 8f52c5a4b69..fd33502e814 100644 --- a/docs/mfc/reference/csinglelock-class.md +++ b/docs/mfc/reference/csinglelock-class.md @@ -4,9 +4,8 @@ title: "CSingleLock Class" ms.date: "11/04/2016" f1_keywords: ["CSingleLock", "AFXMT/CSingleLock", "AFXMT/CSingleLock::CSingleLock", "AFXMT/CSingleLock::IsLocked", "AFXMT/CSingleLock::Lock", "AFXMT/CSingleLock::Unlock"] helpviewer_keywords: ["CSingleLock [MFC], CSingleLock", "CSingleLock [MFC], IsLocked", "CSingleLock [MFC], Lock", "CSingleLock [MFC], Unlock"] -ms.assetid: 7dae7288-8066-4a3e-85e0-78d28bfc6bc8 --- -# CSingleLock Class +# `CSingleLock` Class Represents the access-control mechanism used in controlling access to a resource in a multithreaded program. @@ -22,25 +21,25 @@ class CSingleLock |Name|Description| |----------|-----------------| -|[CSingleLock::CSingleLock](#csinglelock)|Constructs a `CSingleLock` object.| +|[`CSingleLock::CSingleLock`](#csinglelock)|Constructs a `CSingleLock` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CSingleLock::IsLocked](#islocked)|Determines if the object is locked.| -|[CSingleLock::Lock](#lock)|Waits on a synchronization object.| -|[CSingleLock::Unlock](#unlock)|Releases a synchronization object.| +|[`CSingleLock::IsLocked`](#islocked)|Determines if the object is locked.| +|[`CSingleLock::Lock`](#lock)|Waits on a synchronization object.| +|[`CSingleLock::Unlock`](#unlock)|Releases a synchronization object.| ## Remarks -`CSingleLock` does not have a base class. +`CSingleLock` doesn't have a base class. -In order to use the synchronization classes [CSemaphore](../../mfc/reference/csemaphore-class.md), [CMutex](../../mfc/reference/cmutex-class.md), [CCriticalSection](../../mfc/reference/ccriticalsection-class.md), and [CEvent](../../mfc/reference/cevent-class.md), you must create either a `CSingleLock` or [CMultiLock](../../mfc/reference/cmultilock-class.md) object to wait on and release the synchronization object. Use `CSingleLock` when you only need to wait on one object at a time. Use `CMultiLock` when there are multiple objects that you could use at a particular time. +In order to use the synchronization classes [`CSemaphore`](../../mfc/reference/csemaphore-class.md), [`CMutex`](../../mfc/reference/cmutex-class.md), [`CCriticalSection`](../../mfc/reference/ccriticalsection-class.md), and [`CEvent`](../../mfc/reference/cevent-class.md), you must create either a `CSingleLock` or [`CMultiLock`](../../mfc/reference/cmultilock-class.md) object to wait on and release the synchronization object. Use `CSingleLock` when you only need to wait on one object at a time. Use `CMultiLock` when there are multiple objects that you could use at a particular time. -To use a `CSingleLock` object, call its constructor inside a member function in the controlled resource's class. Then call the [IsLocked](#islocked) member function to determine if the resource is available. If it is, continue with the remainder of the member function. If the resource is unavailable, either wait for a specified amount of time for the resource to be released, or return failure. After use of the resource is complete, either call the [Unlock](#unlock) function if the `CSingleLock` object is to be used again, or allow the `CSingleLock` object to be destroyed. +To use a `CSingleLock` object, call its constructor inside a member function in the controlled resource's class. Then call the [`IsLocked`](#islocked) member function to determine if the resource is available. If it is, continue with the remainder of the member function. If the resource is unavailable, either wait for a specified amount of time for the resource to be released, or return failure. After use of the resource is complete, either call the [`Unlock`](#unlock) function if the `CSingleLock` object is to be used again, or allow the `CSingleLock` object to be destroyed. -`CSingleLock` objects require the presence of an object derived from [CSyncObject](../../mfc/reference/csyncobject-class.md). This is usually a data member of the controlled resource's class. For more information on how to use `CSingleLock` objects, see the article [Multithreading: How to Use the Synchronization Classes](../../parallel/multithreading-how-to-use-the-synchronization-classes.md). +`CSingleLock` objects require the presence of an object derived from [`CSyncObject`](../../mfc/reference/csyncobject-class.md). This is usually a data member of the controlled resource's class. For more information on how to use `CSingleLock` objects, see the article [Multithreading: How to Use the Synchronization Classes](../../parallel/multithreading-how-to-use-the-synchronization-classes.md). ## Inheritance Hierarchy @@ -48,9 +47,9 @@ To use a `CSingleLock` object, call its constructor inside a member function in ## Requirements -**Header:** afxmt.h +**Header:** `afxmt.h` -## CSingleLock::CSingleLock +## `CSingleLock::CSingleLock` Constructs a `CSingleLock` object. @@ -62,10 +61,10 @@ explicit CSingleLock( ### Parameters -*pObject*
-Points to the synchronization object to be accessed. Cannot be NULL. +*`pObject`*\ +Points to the synchronization object to be accessed. Can’t be `NULL`. -*bInitialLock*
+*`bInitialLock`*\ Specifies whether to initially attempt to access the supplied object. ### Remarks @@ -76,7 +75,7 @@ This function is generally called from within an access member function of the c [!code-cpp[NVC_MFC_Utilities#19](../../mfc/codesnippet/cpp/csinglelock-class_1.h)] -## CSingleLock::IsLocked +## `CSingleLock::IsLocked` Determines if the object associated with the `CSingleLock` object is nonsignaled (unavailable). @@ -92,7 +91,7 @@ Nonzero if the object is locked; otherwise 0. [!code-cpp[NVC_MFC_Utilities#20](../../mfc/codesnippet/cpp/csinglelock-class_2.h)] -## CSingleLock::Lock +## `CSingleLock::Lock` Call this function to gain access to the resource controlled by the synchronization object supplied to the `CSingleLock` constructor. @@ -102,8 +101,8 @@ BOOL Lock(DWORD dwTimeOut = INFINITE); ### Parameters -*dwTimeOut*
-Specifies the amount of time to wait for the synchronization object to be available (signaled). If INFINITE, `Lock` will wait until the object is signaled before returning. +*`dwTimeOut`*\ +Specifies the amount of time to wait for the synchronization object to be available (signaled). If `INFINITE`, `Lock` will wait until the object is signaled before returning. ### Return Value @@ -111,13 +110,13 @@ Nonzero if the function was successful; otherwise 0. ### Remarks -If the synchronization object is signaled, `Lock` will return successfully and the thread now owns the object. If the synchronization object is nonsignaled (unavailable), `Lock` will wait for the synchronization object to become signaled up to the number of milliseconds specified in the *dwTimeOut* parameter. If the synchronization object did not become signaled in the specified amount of time, `Lock` returns failure. +If the synchronization object is signaled, `Lock` will return successfully and the thread now owns the object. If the synchronization object is nonsignaled (unavailable), `Lock` will wait for the synchronization object to become signaled up to the number of milliseconds specified in the *`dwTimeOut`* parameter. If the synchronization object didn't become signaled in the specified amount of time, `Lock` returns failure. ### Example [!code-cpp[NVC_MFC_Utilities#21](../../mfc/codesnippet/cpp/csinglelock-class_3.h)] -## CSingleLock::Unlock +## `CSingleLock::Unlock` Releases the synchronization object owned by `CSingleLock`. @@ -131,11 +130,11 @@ BOOL Unlock( ### Parameters -*lCount*
-Number of accesses to release. Must be greater than 0. If the specified amount would cause the object's count to exceed its maximum, the count is not changed and the function returns FALSE. +*`lCount`*\ +Number of accesses to release. Must be greater than 0. If the specified amount would cause the object's count to exceed its maximum, the count isn't changed and the function returns `FALSE`. -*lPrevCount*
-Points to a variable to receive the previous count of the synchronization object. If NULL, the previous count is not returned. +*`lPrevCount`*\ +Points to a variable to receive the previous count of the synchronization object. If `NULL`, the previous count isn't returned. ### Return Value @@ -153,5 +152,5 @@ If you need to release more than one access count of a semaphore, use the second ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CMultiLock Class](../../mfc/reference/cmultilock-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CMultiLock` Class](../../mfc/reference/cmultilock-class.md) diff --git a/docs/mfc/reference/run-time-object-model-services.md b/docs/mfc/reference/run-time-object-model-services.md index 4269f4e41b7..7dacf1cfdc3 100644 --- a/docs/mfc/reference/run-time-object-model-services.md +++ b/docs/mfc/reference/run-time-object-model-services.md @@ -3,13 +3,12 @@ description: "Learn more about: Run-Time Object Model Services" title: "Run-Time Object Model Services" ms.date: "03/27/2019" helpviewer_keywords: ["run-time object model services macros"] -ms.assetid: 4a3e79df-2ee3-43a4-8193-20298828de85 --- # Run-Time Object Model Services -The classes [CObject](../../mfc/reference/cobject-class.md) and [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from `CObject` inherit this functionality. +The classes [`CObject`](../../mfc/reference/cobject-class.md) and [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from `CObject` inherit this functionality. -Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information is not supported directly by the C++ language. +Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information isn't supported directly by the C++ language. Serialization is the process of writing or reading an object's contents to or from a file. You can use serialization to store an object's contents even after the application exits. The object can then be read from the file when the application is restarted. Such data objects are said to be "persistent." @@ -17,19 +16,19 @@ Dynamic object creation enables you to create an object of a specified class at The following table lists the MFC macros that support run-time class information, serialization, and dynamic creation. -For more information on these run-time object services and serialization, see the article [CObject Class: Accessing Run-Time Class Information](../../mfc/accessing-run-time-class-information.md). +For more information on these run-time object services and serialization, see the article [`CObject` Class: Accessing Run-Time Class Information](../../mfc/accessing-run-time-class-information.md). ### Run-Time Object Model Services Macros |Name|Description| |-|-| -|[DECLARE_DYNAMIC](#declare_dynamic)|Enables access to run-time class information (must be used in the class declaration).| -|[DECLARE_DYNCREATE](#declare_dyncreate)|Enables dynamic creation and access to run-time class information (must be used in the class declaration).| -|[DECLARE_SERIAL](#declare_serial)|Enables serialization and access to run-time class information (must be used in the class declaration).| -|[IMPLEMENT_DYNAMIC](#implement_dynamic)|Enables access to run-time class information (must be used in the class implementation).| -|[IMPLEMENT_DYNCREATE](#implement_dyncreate)|Enables dynamic creation and access to run-time information (must be used in the class implementation).| -|[IMPLEMENT_SERIAL](#implement_serial)|Permits serialization and access to run-time class information (must be used in the class implementation).| -|[RUNTIME_CLASS](#runtime_class)|Returns the `CRuntimeClass` structure that corresponds to the named class.| +|[`DECLARE_DYNAMIC`](#declare_dynamic)|Enables access to run-time class information (must be used in the class declaration).| +|[`DECLARE_DYNCREATE`](#declare_dyncreate)|Enables dynamic creation and access to run-time class information (must be used in the class declaration).| +|[`DECLARE_SERIAL`](#declare_serial)|Enables serialization and access to run-time class information (must be used in the class declaration).| +|[`IMPLEMENT_DYNAMIC`](#implement_dynamic)|Enables access to run-time class information (must be used in the class implementation).| +|[`IMPLEMENT_DYNCREATE`](#implement_dyncreate)|Enables dynamic creation and access to run-time information (must be used in the class implementation).| +|[`IMPLEMENT_SERIAL`](#implement_serial)|Permits serialization and access to run-time class information (must be used in the class implementation).| +|[`RUNTIME_CLASS`](#runtime_class)|Returns the `CRuntimeClass` structure that corresponds to the named class.| OLE frequently requires the dynamic creation of objects at run time. For example, an OLE server application must be able to create OLE items dynamically in response to a request from a client. Similarly, an automation server must be able to create items in response to requests from automation clients. @@ -39,16 +38,16 @@ The Microsoft Foundation Class Library provides two macros specific to OLE. |Name|Description| |-|-| -|[AFX_COMCTL32_IF_EXISTS](#afx_comctl32_if_exists)|Determines whether the Common Controls library implements the specified API.| -|[AFX_COMCTL32_IF_EXISTS2](#afx_comctl32_if_exists2)|Determines whether the Common Controls library implements the specified API.| -|[DECLARE_OLECREATE](#declare_olecreate)|Enables objects to be created through OLE automation.| -|[DECLARE_OLECTLTYPE](#declare_olectltype)|Declares the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| -|[DECLARE_PROPPAGEIDS](#declare_proppageids)|Declares that the OLE control provides a list of property pages to display its properties.| -|[IMPLEMENT_OLECREATE](#implement_olecreate)|Enables objects to be created by the OLE system.| -|[IMPLEMENT_OLECTLTYPE](#implement_olectltype)|Implements the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| -|[IMPLEMENT_OLECREATE_FLAGS](#implement_olecreate_flags)|Either this macro or [IMPLEMENT_OLECREATE](#implement_olecreate) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. | +|[`AFX_COMCTL32_IF_EXISTS`](#afx_comctl32_if_exists)|Determines whether the Common Controls library implements the specified API.| +|[`AFX_COMCTL32_IF_EXISTS2`](#afx_comctl32_if_exists2)|Determines whether the Common Controls library implements the specified API.| +|[`DECLARE_OLECREATE`](#declare_olecreate)|Enables objects to be created through OLE automation.| +|[`DECLARE_OLECTLTYPE`](#declare_olectltype)|Declares the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| +|[`DECLARE_PROPPAGEIDS`](#declare_proppageids)|Declares that the OLE control provides a list of property pages to display its properties.| +|[`IMPLEMENT_OLECREATE`](#implement_olecreate)|Enables objects to be created by the OLE system.| +|[`IMPLEMENT_OLECTLTYPE`](#implement_olectltype)|Implements the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| +|[`IMPLEMENT_OLECREATE_FLAGS`](#implement_olecreate_flags)|Either this macro or [`IMPLEMENT_OLECREATE`](#implement_olecreate) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. | -## AFX_COMCTL32_IF_EXISTS +## `AFX_COMCTL32_IF_EXISTS` Determines whether the Common Controls library implements the specified API. @@ -60,20 +59,20 @@ AFX_COMCTL32_IF_EXISTS( proc ); ### Parameters -*proc*
-Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode. +*`proc`*\ +Pointer to a `NULL` terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode. ### Remarks -Use this macro to determine whether the Common Controls library the function specified by *proc* (instead of calling [GetProcAddress](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). +Use this macro to determine whether the Common Controls library the function specified by *`proc`* (instead of calling [`GetProcAddress`](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). ### Requirements -afxcomctl32.h, afxcomctl32.inl +`afxcomctl32.h`, `afxcomctl32.inl` -## AFX_COMCTL32_IF_EXISTS2 +## `AFX_COMCTL32_IF_EXISTS2` -Determines whether the Common Controls library implements the specified API (this is the Unicode version of [AFX_COMCTL32_IF_EXISTS](#afx_comctl32_if_exists)). +Determines whether the Common Controls library implements the specified API (this is the Unicode version of [`AFX_COMCTL32_IF_EXISTS`](#afx_comctl32_if_exists)). ### Syntax @@ -83,18 +82,18 @@ AFX_COMCTL32_IF_EXISTS2( proc ); ### Parameters -*proc*
-Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode. +*`proc`*\ +Pointer to a `NULL` terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode. ### Remarks -Use this macro to determine whether the Common Controls library the function specified by *proc* (instead of calling [GetProcAddress](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). This macro is the Unicode version of AFX_COMCTL32_IF_EXISTS. +Use this macro to determine whether the Common Controls library the function specified by *`proc`* (instead of calling [`GetProcAddress`](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). This macro is the Unicode version of `AFX_COMCTL32_IF_EXISTS`. ### Requirements -afxcomctl32.h, afxcomctl32.inl +`afxcomctl32.h`, `afxcomctl32.inl` -## DECLARE_DYNAMIC +## `DECLARE_DYNAMIC` Adds the ability to access run-time information about an object's class when deriving a class from `CObject`. @@ -104,28 +103,28 @@ DECLARE_DYNAMIC(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks -Add the DECLARE_DYNAMIC macro to the header (.h) module for the class, then include that module in all .cpp modules that need access to objects of this class. +Add the `DECLARE_DYNAMIC` macro to the header (`.h`) module for the class, then include that module in all `.cpp` modules that need access to objects of this class. -If you use the DECLARE_ DYNAMIC and IMPLEMENT_DYNAMIC macros as described, you can then use the RUNTIME_CLASS macro and the `CObject::IsKindOf` function to determine the class of your objects at run time. +If you use the `DECLARE_DYNAMIC` and `IMPLEMENT_DYNAMIC` macros as described, you can then use the `RUNTIME_CLASS` macro and the `CObject::IsKindOf` function to determine the class of your objects at run time. -If DECLARE_DYNAMIC is included in the class declaration, then IMPLEMENT_DYNAMIC must be included in the class implementation. +If `DECLARE_DYNAMIC` is included in the class declaration, then `IMPLEMENT_DYNAMIC` must be included in the class implementation. -For more information on the DECLARE_DYNAMIC macro, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information on the `DECLARE_DYNAMIC` macro, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example -See the example for [IMPLEMENT_DYNAMIC](#implement_dynamic). +See the example for [`IMPLEMENT_DYNAMIC`](#implement_dynamic). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## DECLARE_DYNCREATE +## `DECLARE_DYNCREATE` Enables objects of `CObject`-derived classes to be created dynamically at run time. @@ -135,31 +134,31 @@ DECLARE_DYNCREATE(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks The framework uses this ability to create new objects dynamically. For example, the new view created when you open a new document. Document, view, and frame classes should support dynamic creation because the framework needs to create them dynamically. -Add the DECLARE_DYNCREATE macro in the .h module for the class, then include that module in all .cpp modules that need access to objects of this class. +Add the `DECLARE_DYNCREATE` macro in the `.h` module for the class, then include that module in all `.cpp` modules that need access to objects of this class. -If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation. +If `DECLARE_DYNCREATE` is included in the class declaration, then `IMPLEMENT_DYNCREATE` must be included in the class implementation. -For more information on the DECLARE_DYNCREATE macro, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information on the `DECLARE_DYNCREATE` macro, see [`CObject` Class Topics](../../mfc/using-cobject.md). > [!NOTE] -> The DECLARE_DYNCREATE macro includes all the functionality of DECLARE_DYNAMIC. +> The `DECLARE_DYNCREATE` macro includes all the functionality of `DECLARE_DYNAMIC`. ### Example -See the example for [IMPLEMENT_DYNCREATE](#implement_dyncreate). +See the example for [`IMPLEMENT_DYNCREATE`](#implement_dyncreate). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## DECLARE_OLECTLTYPE +## `DECLARE_OLECTLTYPE` Declares the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class. @@ -171,18 +170,18 @@ DECLARE_OLECTLTYPE( class_name ) ### Parameters -*class_name*
+*`class_name`*\ The name of the control class. ### Remarks -`GetUserTypeNameID` and `GetMiscStatus` are pure virtual functions, declared in `COleControl`. Because these functions are pure virtual, they must be overridden in your control class. In addition to DECLARE_OLECTLTYPE, you must add the IMPLEMENT_OLECTLTYPE macro to your control class declaration. +`GetUserTypeNameID` and `GetMiscStatus` are pure virtual functions, declared in `COleControl`. Because these functions are pure virtual, they must be overridden in your control class. In addition to `DECLARE_OLECTLTYPE`, you must add the `IMPLEMENT_OLECTLTYPE` macro to your control class declaration. ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## DECLARE_PROPPAGEIDS +## `DECLARE_PROPPAGEIDS` Declares that the OLE control provides a list of property pages to display its properties. @@ -194,20 +193,20 @@ DECLARE_PROPPAGEIDS( class_name ) ### Parameters -*class_name*
+*`class_name`*\ The name of the control class that owns the property pages. ### Remarks -Use the `DECLARE_PROPPAGEIDS` macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the `BEGIN_PROPPAGEIDS` macro, macro entries for each of your control's property pages, and the `END_PROPPAGEIDS` macro to declare the end of the property page list. +Use the `DECLARE_PROPPAGEIDS` macro at the end of your class declaration. Then, in the `.cpp` file that defines the member functions for the class, use the `BEGIN_PROPPAGEIDS` macro, macro entries for each of your control's property pages, and the `END_PROPPAGEIDS` macro to declare the end of the property page list. For more information on property pages, see the article [ActiveX Controls: Property Pages](../mfc-activex-controls-property-pages.md). ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## DECLARE_SERIAL +## `DECLARE_SERIAL` Generates the C++ header code necessary for a `CObject`-derived class that can be serialized. @@ -217,24 +216,24 @@ DECLARE_SERIAL(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks Serialization is the process of writing or reading the contents of an object to and from a file. -Use the DECLARE_SERIAL macro in an .h module, and then include that module in all .cpp modules that need access to objects of this class. +Use the `DECLARE_SERIAL` macro in an `.h` module, and then include that module in all `.cpp` modules that need access to objects of this class. -If DECLARE_SERIAL is included in the class declaration, then IMPLEMENT_SERIAL must be included in the class implementation. +If `DECLARE_SERIAL` is included in the class declaration, then `IMPLEMENT_SERIAL` must be included in the class implementation. -The DECLARE_SERIAL macro includes all the functionality of DECLARE_DYNAMIC and DECLARE_DYNCREATE. +The `DECLARE_SERIAL` macro includes all the functionality of `DECLARE_DYNAMIC` and `DECLARE_DYNCREATE`. -You can use the AFX_API macro to automatically export the `CArchive` extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code: +You can use the `AFX_API` macro to automatically export the `CArchive` extraction operator for classes that use the `DECLARE_SERIAL` and `IMPLEMENT_SERIAL` macros. Bracket the class declarations (located in the `.h` file) with the following code: [!code-cpp[NVC_MFCCObjectSample#20](../../mfc/codesnippet/cpp/run-time-object-model-services_1.h)] -For more information on the DECLARE_SERIAL macro, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information on the `DECLARE_SERIAL` macro, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -242,9 +241,9 @@ For more information on the DECLARE_SERIAL macro, see [CObject Class Topics](../ ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## IMPLEMENT_DYNAMIC +## `IMPLEMENT_DYNAMIC` Generates the C++ code necessary for a dynamic `CObject`-derived class with run-time access to the class name and position within the hierarchy. @@ -254,17 +253,17 @@ IMPLEMENT_DYNAMIC(class_name, base_class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*base_class_name*
+*`base_class_name`*\ The name of the base class. ### Remarks -Use the IMPLEMENT_DYNAMIC macro in a .cpp module, and then link the resulting object code only once. +Use the `IMPLEMENT_DYNAMIC` macro in a `.cpp` module, and then link the resulting object code only once. -For more information, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -274,11 +273,11 @@ For more information, see [CObject Class Topics](../../mfc/using-cobject.md). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## IMPLEMENT_DYNCREATE +## `IMPLEMENT_DYNCREATE` -Enables objects of `CObject`-derived classes to be created dynamically at run time when used with the DECLARE_DYNCREATE macro. +Enables objects of `CObject`-derived classes to be created dynamically at run time when used with the `DECLARE_DYNCREATE` macro. ``` IMPLEMENT_DYNCREATE(class_name, base_class_name) @@ -286,19 +285,19 @@ IMPLEMENT_DYNCREATE(class_name, base_class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*base_class_name*
+*`base_class_name`*\ The actual name of the base class. ### Remarks -The framework uses this ability to create new objects dynamically, for example, when it reads an object from disk during serialization. Add the IMPLEMENT_DYNCREATE macro in the class implementation file. For more information, see [CObject Class Topics](../../mfc/using-cobject.md). +The framework uses this ability to create new objects dynamically, for example, when it reads an object from disk during serialization. Add the `IMPLEMENT_DYNCREATE` macro in the class implementation file. For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). -If you use the DECLARE_DYNCREATE and IMPLEMENT_DYNCREATE macros, you can then use the RUNTIME_CLASS macro and the `CObject::IsKindOf` member function to determine the class of your objects at run time. +If you use the `DECLARE_DYNCREATE` and `IMPLEMENT_DYNCREATE` macros, you can then use the `RUNTIME_CLASS` macro and the `CObject::IsKindOf` member function to determine the class of your objects at run time. -If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation. +If `DECLARE_DYNCREATE` is included in the class declaration, then `IMPLEMENT_DYNCREATE` must be included in the class implementation. Note that this macro definition will invoke the default constructor for your class. If a non-trivial constructor is explicitly implemented by the class, it must also explicitly implement the default constructor as well. The default constructor can be added to the class's **`private`** or **`protected`** member sections to prevent it from being called from outside the class implementation. @@ -310,11 +309,11 @@ Note that this macro definition will invoke the default constructor for your cla ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## IMPLEMENT_OLECREATE_FLAGS +## `IMPLEMENT_OLECREATE_FLAGS` -Either this macro or [IMPLEMENT_OLECREATE](#implement_olecreate) must appear in the implementation file for any class that uses DECLARE_OLECREATE. +Either this macro or [`IMPLEMENT_OLECREATE`](#implement_olecreate) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. ### Syntax @@ -325,38 +324,38 @@ IMPLEMENT_OLECREATE_FLAGS( class_name, external_name, nFlags, ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*external_name*
+*`external_name`*\ The object name exposed to other applications (enclosed in quotation marks). -*nFlags*
+*`nFlags`*\ Contains one or more of the following flags: - `afxRegInsertable` Allows the control to appear in the Insert Object dialog box for OLE objects. -- `afxRegApartmentThreading` Sets the threading model in the registry to ThreadingModel=Apartment. -- `afxRegFreeThreading` Sets the threading model in the registry to ThreadingModel=Free. +- `afxRegApartmentThreading` Sets the threading model in the registry to `ThreadingModel=Apartment`. +- `afxRegFreeThreading` Sets the threading model in the registry to `ThreadingModel=Free`. -You can combine the two flags `afxRegApartmentThreading` and `afxRegFreeThreading` to set ThreadingModel=Both. See [InprocServer32](/windows/win32/com/inprocserver32) in the Windows SDK for more information on threading model registration. +You can combine the two flags `afxRegApartmentThreading` and `afxRegFreeThreading` to set ThreadingModel=Both. See [`InprocServer32`](/windows/win32/com/inprocserver32) in the Windows SDK for more information on threading model registration. -*l*, *w1*, *w2*, *b1*, *b2*, *b3*, *b4*, *b5*, *b6*, *b7*, *b8* +*`l`*, *`w1`*, *`w2`*, *`b1`*, *`b2`*, *`b3`*, *`b4`*, *`b5`*, *`b6`*, *`b7`*, *`b8`* Components of the class's CLSID. ### Remarks > [!NOTE] -> If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the *nFlags* parameter. If you want to support only the single-treading model, use IMPLEMENT_OLECREATE. +> If you use `IMPLEMENT_OLECREATE_FLAGS`, you can specify which threading model your object supports by using the *`nFlags`* parameter. If you want to support only the single-treading model, use `IMPLEMENT_OLECREATE`. The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server. -The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **WORD**s, and eight **BYTE**s, as represented by *l*, *w1*, *w2*, and *b1* through *b8* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. +The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **`WORD`**s, and eight **`BYTE`**s, as represented by *`l`*, *`w1`*, *`w2`*, and *`b1`* through *`b8`* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. ### Requirements -**Header:** afxdisp.h +**Header:** `afxdisp.h` -## IMPLEMENT_OLECTLTYPE +## `IMPLEMENT_OLECTLTYPE` Implements the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class. @@ -368,29 +367,29 @@ DECLARE_OLECTLTYPE( class_name, idsUserTypeName, dwOleMisc ) ### Parameters -*class_name*
+*`class_name`*\ The name of the control class. -*idsUserTypeName*
+*`idsUserTypeName`*\ The resource ID of a string containing the external name of the control. -*dwOleMisc*
-An enumeration containing one or more flags. For more information on this enumeration, see [OLEMISC](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. +*`dwOleMisc`*\ +An enumeration containing one or more flags. For more information on this enumeration, see [`OLEMISC`](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. ### Remarks -In addition to IMPLEMENT_OLECTLTYPE, you must add the DECLARE_OLECTLTYPE macro to your control class declaration. +In addition to `IMPLEMENT_OLECTLTYPE`, you must add the `DECLARE_OLECTLTYPE` macro to your control class declaration. -The `GetUserTypeNameID` member function returns the resource string that identifies your control class. `GetMiscStatus` returns the OLEMISC bits for your control. This enumeration specifies a collection of settings describing miscellaneous characteristics of your control. For a full description of the OLEMISC settings, see [OLEMISC](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. +The `GetUserTypeNameID` member function returns the resource string that identifies your control class. `GetMiscStatus` returns the `OLEMISC` bits for your control. This enumeration specifies a collection of settings describing miscellaneous characteristics of your control. For a full description of the `OLEMISC` settings, see [`OLEMISC`](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. > [!NOTE] -> The default settings used by the ActiveX ControlWizard are: OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_INSIDEOUT, OLEMISC_CANTLINKINSIDE, and OLEMISC_RECOMPOSEONRESIZE. +> The default settings used by the ActiveX ControlWizard are: `OLEMISC_ACTIVATEWHENVISIBLE`, `OLEMISC_SETCLIENTSITEFIRST`, `OLEMISC_INSIDEOUT`, `OLEMISC_CANTLINKINSIDE`, and `OLEMISC_RECOMPOSEONRESIZE`. ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## IMPLEMENT_SERIAL +## `IMPLEMENT_SERIAL` Generates the C++ code necessary for a dynamic `CObject`-derived class with run-time access to the class name and position within the hierarchy. @@ -400,24 +399,24 @@ IMPLEMENT_SERIAL(class_name, base_class_name, wSchema) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*base_class_name*
+*`base_class_name`*\ The name of the base class. -*wSchema*
+*`wSchema`*\ A UINT "version number" that will be encoded in the archive to enable a deserializing program to identify and handle data created by earlier program versions. The class schema number must not be -1. ### Remarks -Use the IMPLEMENT_SERIAL macro in a .cpp module; then link the resulting object code only once. +Use the `IMPLEMENT_SERIAL` macro in a `.cpp` module; then link the resulting object code only once. -You can use the AFX_API macro to automatically export the `CArchive` extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code: +You can use the `AFX_API` macro to automatically export the `CArchive` extraction operator for classes that use the `DECLARE_SERIAL` and `IMPLEMENT_SERIAL` macros. Bracket the class declarations (located in the `.h` file) with the following code: [!code-cpp[NVC_MFCCObjectSample#20](../../mfc/codesnippet/cpp/run-time-object-model-services_1.h)] -For more information, see the [CObject Class Topics](../../mfc/using-cobject.md). +For more information, see the [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -425,9 +424,9 @@ For more information, see the [CObject Class Topics](../../mfc/using-cobject.md) ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## RUNTIME_CLASS +## `RUNTIME_CLASS` Gets the run-time class structure from the name of a C++ class. @@ -437,14 +436,14 @@ RUNTIME_CLASS(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class (not enclosed in quotation marks). ### Remarks -RUNTIME_CLASS returns a pointer to a [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) structure for the class specified by *class_name*. Only `CObject`-derived classes declared with DECLARE_DYNAMIC, DECLARE_DYNCREATE, or DECLARE_SERIAL will return pointers to a `CRuntimeClass` structure. +`RUNTIME_CLASS` returns a pointer to a [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) structure for the class specified by *`class_name`*. Only `CObject`-derived classes declared with `DECLARE_DYNAMIC`, `DECLARE_DYNCREATE`, or `DECLARE_SERIAL` will return pointers to a `CRuntimeClass` structure. -For more information, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -452,9 +451,9 @@ For more information, see [CObject Class Topics](../../mfc/using-cobject.md). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## DECLARE_OLECREATE +## `DECLARE_OLECREATE` Enables objects of `CCmdTarget`-derived classes to be created through OLE automation. @@ -464,24 +463,24 @@ DECLARE_OLECREATE(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks This macro enables other OLE-enabled applications to create objects of this type. -Add the DECLARE_OLECREATE macro in the .h module for the class, and then include that module in all .cpp modules that need access to objects of this class. +Add the `DECLARE_OLECREATE` macro in the `.h` module for the class, and then include that module in all `.cpp` modules that need access to objects of this class. -If DECLARE_OLECREATE is included in the class declaration, then IMPLEMENT_OLECREATE must be included in the class implementation. A class declaration using DECLARE_OLECREATE must also use DECLARE_DYNCREATE or DECLARE_SERIAL. +If `DECLARE_OLECREATE` is included in the class declaration, then `IMPLEMENT_OLECREATE` must be included in the class implementation. A class declaration using `DECLARE_OLECREATE` must also use `DECLARE_DYNCREATE` or `DECLARE_SERIAL`. ### Requirements -**Header**: afxdisp.h +**Header**: `afxdisp.h` -## IMPLEMENT_OLECREATE +## `IMPLEMENT_OLECREATE` -Either this macro or [IMPLEMENT_OLECREATE_FLAGS](#implement_olecreate_flags) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. +Either this macro or [`IMPLEMENT_OLECREATE_FLAGS`](#implement_olecreate_flags) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. ``` IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) @@ -489,30 +488,30 @@ IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6 ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*external_name*
+*`external_name`*\ The object name exposed to other applications (enclosed in quotation marks). -*l*, *w1*, *w2*, *b1*, *b2*, *b3*, *b4*, *b5*, *b6*, *b7*, *b8* +*`l`*, *`w1`*, *`w2`*, *`b1`*, *`b2`*, *`b3`*, *`b4`*, *`b5`*, *`b6`*, *`b7`*, *`b8`* Components of the class's CLSID. ### Remarks > [!NOTE] -> If you use IMPLEMENT_OLECREATE, by default, you support only the single threading model. If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the *nFlags* parameter. +> If you use `IMPLEMENT_OLECREATE`, by default, you support only the single threading model. If you use `IMPLEMENT_OLECREATE_FLAGS`, you can specify which threading model your object supports by using the *`nFlags`* parameter. The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server. -The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **WORD**s, and eight **BYTE**s, as represented by *l*, *w1*, *w2*, and *b1* through *b8* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. +The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **`WORD`**s, and eight **`BYTE`**s, as represented by *`l`*, *`w1`*, *`w2`*, and *`b1`* through *`b8`* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. ### Requirements -**Header**: afxdisp.h +**Header**: `afxdisp.h` ## See also -[Macros and Globals](mfc-macros-and-globals.md)
-[Isolation of the MFC Common Controls Library](../isolation-of-the-mfc-common-controls-library.md)
+[Macros and Globals](mfc-macros-and-globals.md)\ +[Isolation of the MFC Common Controls Library](../isolation-of-the-mfc-common-controls-library.md)\ [CLSID Key](/windows/win32/com/clsid-key-hklm) diff --git a/docs/preprocessor/hash-include-directive-c-cpp.md b/docs/preprocessor/hash-include-directive-c-cpp.md index 8e27ea23057..f448f611108 100644 --- a/docs/preprocessor/hash-include-directive-c-cpp.md +++ b/docs/preprocessor/hash-include-directive-c-cpp.md @@ -37,7 +37,7 @@ Include files can be *nested*: An **`#include`** directive can appear in a file When include files are nested and when compiling occurs on the command line, directory searching begins in the directory of the parent file. Then it proceeds through the directories of any grandparent files. That is, searching begins relative to the directory that contains the source that's currently being processed. If the file isn't found, the search moves to directories that are specified by the [`/I` (Additional include directories)](../build/reference/i-additional-include-directories.md) compiler option. Finally, the directories that are specified by the `INCLUDE` environment variable are searched. -Within the Visual Studio development environment, the `INCLUDE` environment variable is ignored. The values specified in the project properties for include directories are used instead. For more information about how to set the include directories in Visual Studio, see [Include Directories](../build/reference/vcpp-directories-property-page.md#directory-types) and [Additional Include Directories](../build/reference/c-cpp-prop-page.md#additional-include-directories). +Within the Visual Studio development environment, the `INCLUDE` environment variable is ignored. The values specified in the project properties for include directories are used instead. For more information about how to set the include directories in Visual Studio, see [Include Directories](../build/reference/vcpp-directories-property-page.md#general) and [Additional Include Directories](../build/reference/c-cpp-prop-page.md#additional-include-directories). This example shows file inclusion by using angle brackets: diff --git a/docs/standard-library/basic-ofstream-class.md b/docs/standard-library/basic-ofstream-class.md index 131bb5f0bc0..4f392dde46f 100644 --- a/docs/standard-library/basic-ofstream-class.md +++ b/docs/standard-library/basic-ofstream-class.md @@ -4,11 +4,10 @@ title: "basic_ofstream Class" ms.date: "11/04/2016" f1_keywords: ["fstream/std::basic_ofstream", "fstream/std::basic_ofstream::close", "fstream/std::basic_ofstream::is_open", "fstream/std::basic_ofstream::open", "fstream/std::basic_ofstream::rdbuf", "fstream/std::basic_ofstream::swap"] helpviewer_keywords: ["std::basic_ofstream [C++]", "std::basic_ofstream [C++], close", "std::basic_ofstream [C++], is_open", "std::basic_ofstream [C++], open", "std::basic_ofstream [C++], rdbuf", "std::basic_ofstream [C++], swap"] -ms.assetid: 3bcc9c51-6dfc-4844-8fcc-22ef57c9dff1 --- -# basic_ofstream Class +# `basic_ofstream` Class -Describes an object that controls insertion of elements and encoded objects into a stream buffer of class [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`>, with elements of type `Elem`, whose character traits are determined by the class `Tr`. +Describes an object that controls insertion of elements and encoded objects into a stream buffer of class `basic_filebuf< Elem, Tr>`, with elements of type `Elem`, whose character traits are determined by the class `Tr`. For more information, see [`basic_filebuf`](../standard-library/basic-filebuf-class.md). ## Syntax @@ -19,17 +18,17 @@ class basic_ofstream : public basic_ostream ### Parameters -*Elem*\ +*`Elem`*\ The basic element of the file buffer. -*Tr*\ -The traits of the basic element of the file buffer (usually `char_traits`< `Elem`>). +*`Tr`*\ +The traits of the basic element of the file buffer (usually `char_traits`). ## Remarks -When the **`wchar_t`** specialization of `basic_ofstream` writes to the file, if the file is opened in text mode it will write a MBCS sequence. The internal representation will use a buffer of **`wchar_t`** characters. +When the **`wchar_t`** specialization of `basic_ofstream` writes to the file, if the file is opened in text mode it will write an MBCS sequence. The internal representation will use a buffer of **`wchar_t`** characters. -The object stores an object of class `basic_filebuf`< `Elem`, `Tr`>. +The object stores an object of class `basic_filebuf< Elem, Tr>`. ## Example @@ -57,31 +56,31 @@ int main(int argc, char **argv) |Constructor|Description| |-|-| -|[basic_ofstream](#basic_ofstream)|Creates an object of type `basic_ofstream`.| +|[`basic_ofstream`](#basic_ofstream)|Creates an object of type `basic_ofstream`.| ### Member functions |Member function|Description| |-|-| -|[close](#close)|Closes a file.| -|[is_open](#is_open)|Determines if a file is open.| -|[open](#open)|Opens a file.| -|[rdbuf](#rdbuf)|Returns the address of the stored stream buffer.| -|[swap](#swap)|Exchange the contents of this `basic_ofstream` for the contents of the provided `basic_ofstream`.| +|[`close`](#close)|Closes a file.| +|[`is_open`](#is_open)|Determines if a file is open.| +|[`open`](#open)|Opens a file.| +|[`rdbuf`](#rdbuf)|Returns the address of the stored stream buffer.| +|[`swap`](#swap)|Exchange the contents of this `basic_ofstream` for the contents of the provided `basic_ofstream`.| ### Operators |Operator|Description| |-|-| -|[operator=](#op_eq)|Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that does not leave a copy behind.| +|[`operator=`](#op_eq)|Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that doesn't leave a copy behind.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_ofstream::basic_ofstream +## `basic_ofstream::basic_ofstream` Creates an object of type `basic_ofstream`. @@ -104,25 +103,27 @@ basic_ofstream( ### Parameters -*_Filename*\ +*`_Filename`*\ The name of the file to open. -*_Mode*\ -One of the enumerations in [ios_base::openmode](../standard-library/ios-base-class.md#openmode). +*`_Mode`*\ +One of the enumerations in [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). -*_Prot*\ -The default file opening protection, equivalent to the `shflag` parameter in [_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md). +*`_Prot`*\ +The default file opening protection, equivalent to the `shflag` parameter in [`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md). -*right*\ +*`right`*\ The rvalue reference to the `basic_ofstream` object being used to initialize this `basic_ofstream` object. ### Remarks -The first constructor initializes the base class by calling [basic_ostream](../standard-library/basic-ostream-class.md)(`sb`), where `sb` is the stored object of class [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`>. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`>. +The first constructor initializes the base class by calling `basic_ostream(sb)`, where `sb` is the stored object of class `basic_filebuf< Elem, Tr>`. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`>. -The second and third constructors initializes the base class by calling `basic_ostream`( **sb**). It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`> and then `sb`. [open](../standard-library/basic-filebuf-class.md#open)( `_Filename`, `_Mode` | `ios_base::out`). If the latter function returns a null pointer, the constructor calls [setstate](../standard-library/basic-ios-class.md#setstate)(`failbit`). +The second and third constructors initialize the base class by calling `basic_ostream( sb)`. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`> and then `sb.open( _Filename, _Mode | ios_base::out)`. If the latter function returns a `NULL` pointer, the constructor calls `setstate(failbit)`. -The fourth constructor is a copy function. It initializes the object with the contents of *right*, treated as an rvalue reference. +The fourth constructor is a copy function. It initializes the object with the contents of *`right`*, treated as an rvalue reference. + +For more information, see [`basic_ostream`](../standard-library/basic-ostream-class.md), [`open`](../standard-library/basic-filebuf-class.md#open), and [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example @@ -146,7 +147,7 @@ int main(int argc, char **argv) } ``` -## basic_ofstream::close +## `basic_ofstream::close` Closes a file. @@ -156,13 +157,13 @@ void close(); ### Remarks -The member function calls [rdbuf](../standard-library/basic-ifstream-class.md#rdbuf)**->**[close](../standard-library/basic-filebuf-class.md#close). +The member function calls `rdbuf->close`. For more information, see [`rdbuf`](../standard-library/basic-ifstream-class.md#rdbuf) and [`close`](../standard-library/basic-filebuf-class.md#close). ### Example -See [basic_filebuf::close](../standard-library/basic-filebuf-class.md#close) for an example that uses `close`. +See [`basic_filebuf::close`](../standard-library/basic-filebuf-class.md#close) for an example that uses `close`. -## basic_ofstream::is_open +## `basic_ofstream::is_open` Indicates whether a file is open. @@ -176,7 +177,7 @@ bool is_open() const; ### Remarks -The member function returns [rdbuf](#rdbuf) **->** [is_open](../standard-library/basic-filebuf-class.md#is_open). +The member function returns `rdbuf->is_open`. For more information, see [`rdbuf`](#rdbuf) and [`is_open`](../standard-library/basic-filebuf-class.md#is_open). ### Example @@ -200,7 +201,7 @@ int main( ) } ``` -## basic_ofstream::open +## `basic_ofstream::open` Opens a file. @@ -226,26 +227,29 @@ void open( ### Parameters -*_Filename*\ +*`_Filename`*\ The name of the file to open. -*_Mode*\ -One of the enumerations in [ios_base::openmode](../standard-library/ios-base-class.md#openmode). +*`_Mode`*\ +One of the enumerations in [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). -*_Prot*\ -The default file opening protection, equivalent to the `shflag` parameter in [_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md). +*`_Prot`*\ +The default file opening protection, equivalent to the `shflag` parameter in [`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md). ### Remarks -The member function calls [rdbuf](#rdbuf) **->** [open](../standard-library/basic-filebuf-class.md#open)(_ *Filename*, `_Mode` | `ios_base::out`). If that function returns a null pointer, the function calls [setstate](../standard-library/basic-ios-class.md#setstate)(`failbit`). +The member function calls `rdbuf -> open(_ Filename, _Mode | ios_base::out)`. If that function returns a `NULL` pointer, the function calls `setstate(failbit)`. + +For more information, see [`rdbuf`](#rdbuf), [`open`](../standard-library/basic-filebuf-class.md#open), and [`setstate`](../standard-library/basic-ios-class.md#setstate). + ### Example -See [basic_filebuf::open](../standard-library/basic-filebuf-class.md#open) for an example that uses `open`. +See [`basic_filebuf::open`](../standard-library/basic-filebuf-class.md#open) for an example that uses `open`. -## basic_ofstream::operator= +## `basic_ofstream::operator=` -Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that does not leave a copy behind. +Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that doesn't leave a copy behind. ```cpp basic_ofstream& operator=(basic_ofstream&& right); @@ -253,7 +257,7 @@ basic_ofstream& operator=(basic_ofstream&& right); ### Parameters -*right*\ +*`right`*\ An rvalue reference to a `basic_ofstream` object. ### Return Value @@ -262,9 +266,9 @@ Returns **`*this`**. ### Remarks -The member operator replaces the contents of the object by using the contents of *right*, treated as an rvalue reference. +The member operator replaces the contents of the object by using the contents of *`right`*, treated as an rvalue reference. -## basic_ofstream::rdbuf +## `basic_ofstream::rdbuf` Returns the address of the stored stream buffer. @@ -278,9 +282,9 @@ Returns the address of the stored stream buffer. ### Example -See [basic_filebuf::close](../standard-library/basic-filebuf-class.md#close) for an example that uses `rdbuf`. +See [`basic_filebuf::close`](../standard-library/basic-filebuf-class.md#close) for an example that uses `rdbuf`. -## basic_ofstream::swap +## `basic_ofstream::swap` Exchanges the contents of two `basic_ofstream` objects. @@ -290,16 +294,16 @@ void swap(basic_ofstream& right); ### Parameters -*right*\ +*`right`*\ An `lvalue` reference to another `basic_ofstream` object. ### Remarks -The member function exchanges the contents of this object for the contents of *right*. +The member function exchanges the contents of this object for the contents of *`right`*. ## See also -[basic_ostream Class](../standard-library/basic-ostream-class.md)\ +[`basic_ostream` Class](../standard-library/basic-ostream-class.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[iostreams Conventions](../standard-library/iostreams-conventions.md) +[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostreams` Conventions](../standard-library/iostreams-conventions.md) diff --git a/docs/standard-library/input-streams.md b/docs/standard-library/input-streams.md index 2b4cc5fb3cd..94d5134d6fc 100644 --- a/docs/standard-library/input-streams.md +++ b/docs/standard-library/input-streams.md @@ -3,17 +3,16 @@ description: "Learn more about: Input Streams" title: "Input Streams" ms.date: "11/04/2016" helpviewer_keywords: ["reading data [C++], from input streams", "data [C++], reading from input stream", "input streams", "input stream objects"] -ms.assetid: f14d8954-8f8c-4c3c-8b99-14ddb3683f94 --- # Input Streams -An input stream object is a source of bytes. The three most important input stream classes are [istream](../standard-library/basic-istream-class.md), [ifstream](../standard-library/basic-ifstream-class.md), and [istringstream](../standard-library/basic-istringstream-class.md). +An input stream object is a source of bytes. The three most important input stream classes are [`istream`](../standard-library/basic-istream-class.md), [`ifstream`](../standard-library/basic-ifstream-class.md), and [`istringstream`](../standard-library/basic-istringstream-class.md). -The `istream` class is best used for sequential text-mode input. You can configure objects of class `istream` for buffered or unbuffered operation. All functionality of the base class, `ios`, is included in `istream`. You will rarely construct objects from class `istream`. Instead, you will generally use the predefined `cin` object, which is actually an object of class [ostream](../standard-library/basic-ostream-class.md). In some cases, you can assign `cin` to other stream objects after program startup. +The `istream` class is best used for sequential text-mode input. You can configure objects of class `istream` for buffered or unbuffered operation. All functionality of the base class, `ios`, is included in `istream`. You'll rarely construct objects from class `istream`. Instead, you'll generally use the predefined `cin` object, which is actually an object of class [`ostream`](../standard-library/basic-ostream-class.md). In some cases, you can assign `cin` to other stream objects after program startup. The `ifstream` class supports disk file input. If you need an input-only disk file, construct an object of class `ifstream`. You can specify binary or text-mode data. If you specify a filename in the constructor, the file is automatically opened when the object is constructed. Otherwise, you can use the `open` function after invoking the default constructor. Many formatting options and member functions apply to `ifstream` objects. All functionality of the base classes `ios` and `istream` is included in `ifstream`. -Like the library function `sscanf_s`, the `istringstream` class supports input from in-memory strings. To extract data from a character array that has a null terminator, allocate and initialize the string, then construct an object of class `istringstream`. +Like the library function `sscanf_s`, the `istringstream` class supports input from in-memory strings. To extract data from a character array that has a `NULL` terminator, allocate and initialize the string, then construct an object of class `istringstream`. ## In This Section @@ -27,8 +26,8 @@ Like the library function `sscanf_s`, the `istringstream` class supports input f [Input Stream Member Functions](../standard-library/input-stream-member-functions.md) -[Overloading the >> Operator for Your Own Classes](../standard-library/overloading-the-input-operator-for-your-own-classes.md) +[Overloading the `>>` Operator for Your Own Classes](../standard-library/overloading-the-input-operator-for-your-own-classes.md) ## See also -[iostream Programming](../standard-library/iostream-programming.md) +[`iostream` Programming](../standard-library/iostream-programming.md)